Metadata-Version: 2.4
Name: nl2data-admin-service
Version: 0.1.0
Summary: Optional transport-neutral admin control-plane service for the nl2data-core metadata-to-Bundle lifecycle.
Author: NL2Data Contributors
License: Apache-2.0
Keywords: nl2data,admin,service,semantic catalog,metadata
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: nl2data-core>=0.1.0
Requires-Dist: pydantic<3,>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"

# nl2data-admin-service

Optional transport-neutral admin control-plane service for the nl2data-core metadata-to-Bundle lifecycle.

## Overview

This package exposes a framework-neutral application service that hosts can wrap with their chosen transport (HTTP, CLI, UI, etc.). It intentionally has no HTTP, web-framework, authentication, or database-driver dependencies, keeping `nl2data` and `nl2data_core` transport-free and embeddable.

## Installation

```bash
pip install -e packages/nl2data-admin-service
```

## Usage

```python
from nl2data_admin_service import AdminService, AdminServiceConfig
from nl2data_admin_service.auth import AuthContext, Permission

# Host provides dependencies and authentication context.
service = AdminService(dependencies, AdminServiceConfig())
context = AuthContext(
    operator_id="operator-1",
    tenant_scope_fingerprint="sha256:...",
    permissions=frozenset([Permission.SNAPSHOT_READ]),
)
snapshot = service.get_snapshot("sha256:...", auth_context=context)
```

## Design

- **Transport-neutral**: Service methods accept and return bounded Pydantic DTOs.
- **Host-owned authentication**: The host supplies a trusted `AuthContext`; the service fails closed when it is missing.
- **Tenant/source scoped**: Every read and mutation is scoped by the host-provided tenant/source fingerprint.
- **Safe projection**: DTOs expose only opaque identifiers, fingerprints, versions, and bounded provenance.
- **Idempotent**: Mutating commands require an idempotency key and expected fingerprints/revisions.

## Assembly lifecycle

The service projects the core lifecycle without reimplementing it:

1. `create_draft(...)` or `create_draft_from_proposals(...)` creates an
    `AssemblyDraft` in `draft` state. Draft DTOs expose state, assertion counts,
    safe payload hashes, provenance kinds, redacted deployment-reference schemes,
    and `draft_revision`, but no Bundle fingerprint.
2. `submit_draft_for_review(...)` moves the draft to `review`.
    `decide_draft_assertion(...)` approves, rejects, or edits one assertion; each
    mutation requires the current revision, and payload edits invalidate review.
3. `approve_assembly_draft(...)` freezes a fully reviewed draft in `approved`.
4. `publish_draft(...)` delegates verification, publish-time fingerprinting,
    accepted-assertion manifest derivation, audit creation, idempotency, and
    supersession to core/catalog. Direct `publish_bundle(...)` is rejected.
5. `activate_published_fingerprint(...)` and
    `rollback_published_fingerprint(...)` move the active pointer among immutable
    publications. `list_published_versions(...)` reports `available`, `active`,
    `superseded`, `deprecated`, and `retired` state with predecessor/successor and
    audit references.

Lifecycle mutations require both the matching `Permission` and a trusted
host-authorized Author, Reviewer, Approver, or Publisher role. Draft revision
conflicts return normalized `conflict`; missing roles return
`authorization_denied`. Publish outcomes contain bounded issue codes and safe
references only, never assertion payloads, resolved connections, or raw operator
identities.

## Verification Suite

`await verify_draft(...)` requires `assembly:verify`, an expected draft revision,
and a configured policy profile. The host supplies the trusted verification
executor and candidate-bound execution-context factory. Verification may use
temporary fixtures and ephemeral secret resolution, but it does not mutate the
draft, approval state, catalog, or active pointer.

Planned publication uses `PublishDraftCommand` with the selected policy and
fresh `VerificationSuiteEvidence`. The service passes those bindings to core;
it does not reinterpret skipped, unavailable, timed-out, failed, or not-run
outcomes. `get_verification_evidence(...)` requires `assembly:audit` and returns
only bounded suite/layer/case statuses, counts, issue codes, identities, and
fingerprints. Queries, observations, expected or actual values, physical names,
deployment references, credentials, and backend exceptions never enter Admin
result DTOs.

## Semantic authoring

`validate_authoring(...)` accepts `AuthoringDocumentCommand`, requires
`bundle:validate` permission and authorized source scope, and returns only a
bounded semantic summary or safe source-located diagnostics. It never reads or
writes the draft store.

`import_authoring(...)` accepts `ImportAuthoringCommand`, requires
`assembly:write` permission plus the trusted `author` lifecycle role, derives
the author reference from `AuthContext`, and persists through `create_draft`.
Imported assertions always begin pending in a revision-zero `draft`; authoring
cannot review, approve, publish, or activate content.

Capabilities advertise the supported authoring API version and effective
maximum input size. The built-in limit is 1 MiB and may be reduced by
`AdminServiceConfig.max_body_size_bytes`.

## Service Contract Versioning

The service exposes a versioned command/result schema via `nl2data_admin_service.schema.build_schema(contract_version)`. Host transports can introspect this schema to bind requests and responses without hard-coding DTO shapes.
