# Aitvaras Service Package Contract — v0.1 draft

Status: open experimental proposal, not an industry standard. Date: 2026-10-03.

A **service** is a capability clients consume: signing, policy evaluation, trading automation, liquidation, or gas sponsorship. A **release** is an immutable software package and its evidence. An **instance** is a running deployment in a customer environment. A container/EIF is an artifact, not the product name. "Executor" describes an internal runtime adapter.

## Reuse standards at each layer

| Layer | Reuse | Aitvaras addition / boundary |
|---|---|---|
| Container packaging | [OCI Image, Runtime and Distribution](https://opencontainers.org/); [Distribution manifests, subjects and referrers](https://specs.opencontainers.org/distribution-spec/) | Keep image digests and attached evidence; pilot accepts uploaded archives/EIFs. Registry pull/referrer support is future work. |
| Build identity and provenance | [in-toto statements through Sigstore/Cosign](https://docs.sigstore.dev/cosign/verifying/attestation/) | Reference original signed evidence. A checksum is integrity data, not publisher authentication. No implemented signature verifier yet. |
| Deployment/runtime | [Confidential Containers](https://confidentialcontainers.org/docs/overview/) with Kata/Kubernetes; [dstack](https://phala.com/dstack) offers a Compose-oriented approach | These are different runtime ecosystems, not one universal deployment format. Nitro is a separate adapter; do not assume CoCo supports Nitro. |
| Remote trust | [IETF RATS architecture, RFC 9334](https://www.rfc-editor.org/rfc/rfc9334.html); [EAT claims, RFC 9711](https://www.rfc-editor.org/rfc/rfc9711.html) | Separate attester, verifier, reference values, appraisal policy and relying party. RATS is an informational architecture; EAT does not make all hardware evidence interchangeable. |
| Attestation and secret release | [Trustee KBS/AS/RVPS](https://confidentialcontainers.org/docs/attestation/); [AWS Nitro cryptographic attestation](https://docs.aws.amazon.com/enclaves/latest/user/set-up-attestation.html) | Provider profiles own evidence verification, trusted roots, freshness, debug restrictions and key release. PCRs are AWS-profile data, not universal service fields. |
| Catalog, tenant access and workflow | Versioned JSON Schema / OpenAPI | Small open Aitvaras contract for service descriptions, dependency declarations, packages, revisions and approval. |

The conclusion that no single universal hosting format covers these layers is an architectural assessment of these specifications, not a standards body's declaration.

## Markdown and JSON together

Use `SERVICE.md` for descriptions, operating instructions, limitations, examples and agent context. Use `service.json` for validated catalog metadata and `release.json` for immutable artifact facts. Markdown may contain fenced JSON that intake can recover; ambiguous prose remains a proposal. JSON is authoritative for backend actions after validation and review. No executable commands are derived automatically from Markdown.

Suggested layout (not all files mandatory):

```
service.json                # portable public-safe description
release.json                # immutable version + actual hashes + provider profile
SERVICE.md                  # human/agent guide, dependencies, operations, recovery
artifacts/                  # signed EIF or OCI archive, supporting files
config/                     # templates only; no live credentials
policies/                   # attestation and authorization policies
signatures/                 # signatures, public certificates, provenance bundles
 evidence/                  # compatibility/test reports and their scope
```

A valid release inventories all referenced artifact, signature, certificate, policy and evidence files with computed SHA256 and size. It does not inventory itself to avoid a recursive self-hash. The outer package hash is submitted separately in its upload reservation. Versions cannot be reused after reservation; incomplete/expired uploads need a new version in this pilot.

## Separate records and authority

1. Service description: name, category, publisher/license, networks/protocols, runtime targets, client interfaces, dependencies, configuration **keys/types**, readiness and optional namespaced `extensions`.
2. Release: exact version, runtime adapter, architecture, files, artifact hash, signature references, compatibility evidence, resource requirements and provider attestation profile.
3. Environment: private actual endpoints, cloud account, network placement and secret references. Never copy these into a public description. Existing environment APIs remain separate.
4. Deployment: concrete plan, human approval bound to plan/release/environment revisions, and instance status. Hosted catalog intake does not yet implement this execution contract.

Private is the default. Organization API keys cannot set organization IDs, mint other keys, approve public listings, or deploy. A site administrator approves one catalog revision. New draft edits do not change the previously approved snapshot. Public approval never grants artifact downloads. Withdraw removes the public snapshot.

## Provider profiles and future adapters

The current `aws-nitro` release profile uses nonzero expected PCR0/PCR8, signed-image declaration and `debugAllowed:false`. Static supplied PCRs are expected reference values, not a fresh attestation. The pilot still requires independent signature verification and runtime attestation checks.

`intel-tdx`, `amd-sev-snp`, and `custom` schema profiles reference inventoried reference-values and policy files plus a verifier identifier. These are declarations for future adapters, **not supported deployments or working verifiers**. The pilot deployer remains AWS Nitro only. Namespaced `extensions` permit experiments without silently changing core fields. Unknown core fields are rejected; negotiated future major versions can change them.

## Intake from messy documents and archives

Flow: local bounded scanner → hashed inventory and reviewed text excerpts → deterministic manifest recovery/candidate extraction → Jev choices → intake proposal and gaps → owner validates manifests → private upload → independent verification → explicit approval.

The scanner accepts folders, Markdown/JSON files, TAR/TAR.GZ and ZIP. It reads without extracting, running scripts or recursively unpacking nested archives. It rejects traversal, duplicate paths, symlinks, hard links, devices, sparse/encrypted entries and configured size/count limits. It withholds likely secret/configuration files and suspicious credential-bearing text. Review excerpts before sending: heuristic filtering is not a guarantee against every possible secret.

[Jev's official API](https://docs.typesafe.ai/api) accepts state and typed questions. [Pre-parsed extraction](https://docs.typesafe.ai/cookbooks/pre_parsed_value_extraction_cookbook) selects values found by ordinary code. Use one batched decision request to classify runtime/category, dependency requirements and select among observed release-version candidates. Every answer stays labeled `needsReview:true`; confidence is not evidence of signature validity or measured compatibility. The pinned-source hash is provenance for the excerpt, not a cryptographic publisher identity.

Missing names, measured PCRs, signatures, key ownership, exact dependency versions, supported network IDs, licensing permission or test evidence stay missing. Conflicting versions remain unresolved. A separate generative agent can draft explanatory Markdown or propose schema fields, with source citations; deterministic validation and human approval still control writes. No model may fabricate hashes, attestations, credentials, approvals or test results.

## Open adoption

The schema, public guide and generic examples are portable and independent of Aitvaras hosting or a particular model. Use any client capable of HTTP/JSON. Treat v1alpha1 as experimental; preserve uploaded original files and evidence for reprocessing. Do not confuse openness of this contract with licensing rights to third-party software.

The contract text and JSON schemas created for this interface are offered under CC0-1.0. This dedication does not apply to vendor artifacts, credentials, or the rest of the project. No external standards certification is claimed.