@opensoha/contracts 0.1.29 → 0.2.0

package/COMPATIBILITY.md

@@ -1,18 +1,27 @@
 # Compatibility and Versioning
 
-This repository owns the public OpenSoha contract surface. Consumers should
-pin released versions and treat this repository as the first place where public
+The Root `contracts/` workspace owns the public OpenSoha contract surface. Consumers should
+pin released versions and treat this workspace as the first place where public
 API, schema, and SDK behavior changes are proposed.
 
 ## Version Streams
 
-Current stream: `0.1.x`.
+Current source metadata stream: `0.2.x` (`0.2.0` namespace-migration candidate).
+
+The Go source identity is now `github.com/opensoha/soha/contracts` in the
+`opensoha/soha` Root repository, directory `contracts`. This namespace move
+changes Go imports and is an intentional `0.x` minor migration for B5, not an
+optional `0.1.x` patch addition. The candidate source version does not establish
+a public release under the new module path. Public HTTP/schema/DTO semantics
+and the existing schema compatibility baseline are unchanged by this move.
+The `0.2.x` stream retains the additive patch rules and schema guards documented
+below for `0.1.x`; only the Go source namespace changes in `0.2.0`.
 
 - `0.x` releases may still evolve quickly, but compatibility gates must run for
   every change.
-- `0.1.x` patch releases may add optional fields, optional query parameters,
+- `0.1.x` and `0.2.x` patch releases may add optional fields, optional query parameters,
   new enum values, new response status codes, new operations, and new schemas.
-- `0.1.x` patch releases must not remove existing operations, rename
+- `0.1.x` and `0.2.x` patch releases must not remove existing operations, rename
   `operationId` values, remove response status codes, remove schema properties,
   add required request properties, remove enum values, or narrow existing
   schema types.
@@ -37,12 +46,12 @@ follow the partial HTTP schema. Both full and partial requests use the same endp
 Each release must keep these values aligned:
 
 - `package.json` `version`
-- `package-lock.json` root package version
+- Root `package-lock.json` `packages["contracts"].version`
 - `openapi/soha-api.yaml` `info.version`
 - `gen/go/sohaapi/client.go` default user agent version
-- Git tag `v<version>`
+- SDK Git tag `contracts/v<version>`
 - Go module tag for consumers importing
-  `github.com/opensoha/soha-contracts/gen/go/sohaapi`
+  `github.com/opensoha/soha/contracts/gen/go/sohaapi`
 
 The version sync gate runs with:
 
@@ -52,20 +61,32 @@ npm run check:version-sync
 
 The gate fails when any of the synchronized versions diverge. In GitHub tag
 release workflows it also verifies that the pushed tag is exactly
-`v<package.json version>`.
+`contracts/v<package.json version>`. Core `v*` and other component tags are
+not SDK release tags and do not trigger SDK tag-version comparison.
 
-Release order for `0.1.x`:
+Release order (after the B5 namespace/version decision):
 
-1. Update `package.json`, `package-lock.json`, and OpenAPI `info.version` to
-   the same patch version.
+1. Align `package.json`, Root lock `packages["contracts"]`, OpenAPI versions
+   and the client user agent. The namespace migration requires a `0.x` minor
+   version; do not publish the retained `0.1.29` candidate as a migrated patch.
 2. Regenerate SDKs when OpenAPI changed.
 3. Run `npm test`, `npm pack --dry-run`, `npm run release:artifacts`, and
    the consumer matrix.
-4. Create tag `v<version>`.
-5. Let the release workflow stage the npm package with `NPM_TOKEN`. After a
-   maintainer approves the stage with 2FA, dispatch recovery for the same tag.
+4. Create the immutable SDK tag `contracts/v<version>` after acceptance.
+5. B5 must first enable Root `.github/workflows/contracts-release.yml` for
+   `contracts/v*`. Local artifact policy metadata only describes that expected
+   publisher; it is not a signed attestation or registry availability proof.
+   Let that protected publisher stage the npm package with GitHub Actions OIDC
+   trusted publishing (no token fallback). Its release-control gate requires the
+   legacy publishers disabled and drained before any external write. After a
+   maintainer approves the stage with 2FA, dispatch recovery for the same tag
+   with `stage_run_id` set to the original successful stage workflow run. Recovery
+   verifies its Root workflow/tag/SHA and reuses that run's original staged
+   artifacts; missing or expired artifacts block recovery, never trigger repacking.
    The workflow verifies the public npm package and Go tag before attaching
    the tarball, checksums, and release manifest to the GitHub release.
+   GitHub assets are immutable: the shared publisher compares existing bytes and
+   uploads only missing files, without changing Core's latest release.
 
 ## Compatibility Baseline
 
@@ -373,6 +394,14 @@ resource/action meaning, or make a legacy alias authorize a broader action.
 Coarse keys become non-assignable before removal, and are removed only after
 role migration and consumer conformance prove no active dependency.
 
+Docker runtime directory listing and file content require the independently
+assignable `docker.services.files` permission. Volume mount metadata remains
+under `docker.services.view`. Neither the view permission nor a legacy alias
+grants file access. Existing default operator/developer roles receive an
+explicit file grant on the Core side; custom roles must opt in. This closes
+an overbroad read boundary without changing endpoint shapes. A selected project
+and host must still pass the server-resolved scope check before Agent access.
+
 ## Consumer Adoption
 
 Session access tokens may add the optional positive `authzVersion` claim. Core
@@ -430,6 +459,16 @@ Local runs skip missing sibling checkouts by default. CI and release candidate
 validation should use `--require-all` or a specific `--consumer <name>` so a
 missing checkout is a failure.
 
+Candidate source and declared dependency validation are distinct results. CI runs
+both even when the declared step fails; either failure keeps the existing consumer
+job failed. Manual CI may select an explicit full `contracts_sha`, while consumer
+pins remain unchanged. Local candidate checks can bind `--contracts-sha` and, for
+uncommitted source, `--contracts-source-hash` before any consumer executes. Reports
+record the requested and actual Contracts identity and actual consumer source.
+Dry-run discovery is not a passed build, and candidate checks do not prove published
+package availability. See [Consumer Matrix](./README.md#consumer-matrix) for commands
+and the separately retained mode reports.
+
 ## Capability lifecycle metadata
 
 `execution.checks` adds optional version-pinned references to read-only availability,
@@ -565,3 +604,88 @@ this SDK alone does not enable the feature or validate a production deployment.
 Consumers must pin the actually published npm/Go artifacts and validate the
 released combination; local tarballs and provenance policy files do not prove
 registry publication or an npm provenance attestation.
+
+
+## Docker project execution identity v1 (Task115 candidate)
+
+`runtimeProtocols` is an optional additive claim field. A missing protocol never
+claims an operation containing `runtimeBinding`; unknown versions remain queued.
+New control-plane-created projects may opt into `docker-project-identity-v1`.
+Existing rows remain legacy and are not silently adopted or renamed. The binding
+contains immutable database Host/Project UIDs and their deterministic Compose
+namespace; the execution copy reserves identity labels and rejects explicit
+`container_name`. Original configuration is retained. Every Compose invocation must explicitly use `-p <namespace>`; the top-level
+name alone is insufficient because environment variables take precedence.
+Both runner and runtime queries use this same namespace. Compose include/extends
+are explicitly unsupported until resolved configuration can be verified. Container reads require the full Engine ID,
+Compose project/service labels and both resource UIDs; labels do not authenticate
+an untrusted runtime. A replacement ID is a conflict, never a name-based retry.
+A new Agent API version is required for safe file/PTY operations; no fallback to
+legacy shell file access is permitted. These are candidate protocol semantics,
+not evidence of a published SDK, live migration or production enablement.
+
+Bound service start/stop/restart freezes the full container ID in
+`runtimeContainer`; the runner observes that ID and acts on that same ID. A
+project-wide operation also freezes an explicit `runtimeContainers` array from
+the control plane's registered full IDs, under its project transaction lock.
+Before a project command the actual namespace must match that whole set; a
+missing snapshot, unexpected member or replacement CID blocks dispatch, even
+when labels match. A fresh deployment freezes an explicit empty array.
+A
+successful observation of the entire project namespace sets callback
+`runtimeInventoryConfirmed: true` and includes `services`, including an explicit
+empty array. Only this complete, bounded, unique-name/full-ID inventory may clear
+an absent service's runtime ID and mark it removed; its configuration record is
+retained. Missing, malformed or unconfirmed observations never clear inventory.
+Compose namespace checks assume a trusted Docker daemon and writers; labels do
+not isolate a malicious process with privileged access to that same daemon.
+
+## Docker runtime read v1 (Task115 candidate)
+
+`docker-runtime-read-v1` carries only the full registered container binding,
+project reference and bounded action options. No Compose configuration,
+environment, Agent credential or daemon host-source path crosses this protocol.
+The Agent must observe the exact full CID and all identity coordinates before
+reading. Its response returns the same binding; consumers reject missing,
+different or unsupported protocol responses without falling back to legacy
+Compose-name or shell-file reads. Runtime file content is UTF-8 text with explicit
+size/truncation; a bounded directory result states whether it is complete.
+Missing kernel/reader-image/action capability fails closed. This source protocol
+and its Go helper are not evidence of a published SDK or implemented Agent/Core
+file/PTY support.
+
+Versioned read responses bind the complete original request and require explicit arrays and completeness. For `files.read`, `sizeBytes` reports the full observed source file size and `returnedBytes` counts the returned UTF-8 payload; truncation must agree with the difference. Log byte counts describe returned content. Files and logs never imply a coherent ongoing stream snapshot. Agent read action policies apply to both versioned and legacy route families: existing deployments explicitly add `docker.runtime.logs` / `docker.runtime.files` to use the corresponding reads after upgrade. Legacy wire formats remain accepted when allowlisted, and are never a fallback for identity-bound reads.
+
+The additive `/docker/projects/{dockerProjectID}/runtime/v1/{logs,volumes,files,file}` GET family is identity-bound and never forwards caller-supplied UID/CID values. Logs uses docker.services.logs; mount metadata and files use docker.services.files plus the existing resource scope. Caller query controls are action-specific. Old paths are retained. New endpoints reject unbound projects and do not fall back to legacy agents. Identity v1 represents one container per service, so explicit scale/replicas must be literal 1 and deploy mode must be replicated; dynamic or multi-replica shapes are rejected before runtime execution.
+
+## Manifest publication admission v1
+
+`manifest_delivery_v1.` is an opt-in provider family, not a change to legacy
+providers. New Core uses it for Plan-bound Manifest tasks only after an Agent
+advertises `manifest.delivery-admission.v1`. The claim response header
+`X-Soha-Manifest-Admission-Version: 1` confirms current Core admission for that
+claim, not a permanent grant. Missing, repeated, or different confirmation prevents
+execution on a new runner, even if an older Core accepted the provider string.
+Old runners and Direct workers do not claim this family. No legacy fallback is
+allowed. Private Plan/target context is not runner payload or a new public DTO.
+Rollback must settle or cancel protected tasks before removing the new workers;
+retain the additive private operation column and do not rewrite task providers.
+
+New runners also reject known old application Plan tasks (`fieldManager` begins
+`opensoha-manifest/` or `initializationPlanId` is nonempty) returned on legacy
+providers. This prevents an old Core from being treated as a standalone Manifest
+executor for those Plans. Markers are rejection hints only, not identity or grants.
+Unassociated standalone tasks and read-only Git synchronization keep their behavior.
+
+## Pod session identity in Agent mode
+
+Core sends UID-bound log snapshots, log streams and terminals to the Agent
+GET routes under `/api/v1/platform/workloads/pods/:name/uid-bound/` with
+`expectedUid`. The matching suffixes are `logs`, `logs/stream` and `terminal`.
+Each route uses the corresponding existing action authorization and requires a
+live UID match on the Agent before opening the subresource. Returning a UID in
+Pod detail does not imply support for these routes.
+
+Core fails closed if the Agent lacks the bound route. It never retries a
+UID-bound operation through a legacy route, including during rollback or a mixed
+Agent rollout. Requests without a UID continue to use the existing routes.

package/README.md

@@ -1,8 +1,8 @@
-# soha-contracts
+# Soha Contracts
 
 Shared public contracts for OpenSoha.
 
-This repository is the source of truth for schemas consumed across Soha core,
+The `contracts/` workspace in `opensoha/soha` is the source of truth for schemas consumed across Soha core,
 Soha CLI, Soha Agent, Soha Web, Soha App, official skills, connectors, and Soha
 Cloud services. Product repositories should depend on generated SDKs, HTTP
 APIs, JSON Schemas, or released artifacts from this repository instead of
@@ -64,8 +64,8 @@ personal environments.
 
 Current SDK entry points:
 
-- Go: `github.com/opensoha/soha-contracts/gen/go/sohaapi`
-- Go OpenAPI artifact: `github.com/opensoha/soha-contracts/openapi`
+- Go: `github.com/opensoha/soha/contracts/gen/go/sohaapi`
+- Go OpenAPI artifact: `github.com/opensoha/soha/contracts/openapi`
 - TypeScript: `@opensoha/contracts/gen/ts/sohaapi`
 - npm OpenAPI artifacts: `@opensoha/contracts/openapi/soha-api.yaml` and
   `@opensoha/contracts/openapi/soha-api.json`
@@ -84,6 +84,14 @@ capabilities, and versioned Outpost agent messages. Sensitive enrollment and
 protocol inputs are write-only; response DTOs exclude private keys and raw
 SAML assertions.
 
+The `resource` package also provides `PodArgvToolInput` and
+`PodExecutionLookupInput` helpers for the closed Gateway Pod execution schemas.
+They validate targets, original references and bounded runtime input. They do
+not grant execution permission or bypass Gateway approval; the consuming
+Gateway must register and enforce the capability. The Go HTTP generator prunes
+schemas that are used only by Gateway tools, so these semantic helpers remain
+hand-maintained alongside `PodArgvInput`.
+
 ```sh
 npm run generate
 npm run check:generated
@@ -118,7 +126,7 @@ calling code in the consumer until those APIs are promoted into the supported
 client surface. Redirect-oriented flows such as OIDC provider redirects should
 not use the JSON-only `doJSON` helper until a non-JSON client mode is added.
 
-The Go generator and generated DTO checks run with Go 1.27.3 in CI.
+The Go generator and generated DTO checks run with Go 1.27.4 in CI.
 
 ## Validation
 
@@ -162,6 +170,25 @@ npm run check:openapi-breaking:update
 Do not update the baseline just to silence an unexpected breaking-change
 failure.
 
+## Same-repository source workspace
+
+Install once from the repository root with `npm ci`; the root `package-lock.json`
+is the only installation input for `contracts/` and `web/`. Run component scripts
+with `npm run <script> --workspace contracts`, or from `contracts/` after that install.
+Public Go module and npm package identities remain unchanged during this transition.
+
+```sh
+npm run check:consumers --workspace contracts -- --internal-source --out /path/to/internal-source.json
+```
+
+This checks Core at the root with the exact root `go.work`, and Web through the
+local npm workspace SDK link. It does not install packages, rewrite manifests or
+prove that an SDK version has been published. Reports label this `internal-source`
+and bind the source revision plus workspace input digests. Use `--consumer soha`
+or `--consumer soha-web` to select one; `--declared` cannot be combined with this mode.
+The executable workflow is [root Contracts CI](../.github/workflows/contracts-ci.yml).
+Nested legacy publishing workflows are inert; publisher migration remains a separate B4/B5 stage.
+
 ## Consumer Matrix
 
 Network runtime schemas and network-access DTOs require `0.1.17` or later;
@@ -170,7 +197,9 @@ use the local consumer matrix below: it packs this checkout for Web/App and
 supplies an isolated Go workspace. After publishing, update consumer versions
 and lockfiles and verify them without the local override.
 
-The cross-repository consumer gate is:
+The external compatibility gate retains all six consumers in two separate modes.
+Place their checkouts outside the source npm workspace and set `SOHA_CONSUMER_ROOT`.
+The external candidate gate is:
 
 ```sh
 npm run check:consumers
@@ -189,14 +218,85 @@ npm run check:consumers -- --consumer soha-skills --require-all
 ```
 
 Go consumers run in a temporary `go.work` that replaces the contracts module
-with this checkout. `soha-web` and `soha-app/frontend` run `npm ci`, install a packed copy of this
-checkout without changing their dependency manifests or lockfiles, and build
-against that package. The App pin represents its recorded committed source;
-local uncommitted Native adaptations need separate worktree evidence and a new
-reviewed pin after they are committed.
+with this checkout. For npm consumers, the checker packs this checkout, temporarily
+resolves the SDK tarball into `package.json` and `package-lock.json` with
+`npm install --package-lock-only --ignore-scripts`, then runs `npm ci` and the
+consumer build. Both files are restored byte-for-byte on success or failure.
+Run against an exclusively owned staging checkout or reserve dependency installation
+and builds in the selected worktrees for the duration of the check. Installation
+changes `node_modules` and builds produce the consumer's normal output.
 
-Use `--dry-run` to inspect the discovered commands without executing consumer
-builds.
+`SOHA_CONSUMER_ROOT` selects an explicit sibling checkout group, including local
+candidate worktrees with uncommitted source. For example:
+
+```sh
+SOHA_CONSUMER_ROOT=/path/to/candidate-group npm run check:consumers -- --require-all --out /path/to/evidence/candidate-consumers.json
+```
+
+Reports identify the contracts and consumer HEADs plus SHA-256 hashes of modified,
+staged, deleted and untracked source files; failures are recorded and return a
+nonzero exit status after the selected matrix finishes. The source hashes identify
+worktree contents, not a release artifact. Keep the candidate stable throughout the
+run. `--dry-run` inspects discovery and commands without running consumer builds.
+`--declared` separately checks the consumer's original SDK dependency without
+source substitution. Neither candidate worktree checks nor declared checks change
+the fixed revision selection in CI or prove that unpublished packages are released.
+
+Bind a clean candidate checkout to its full, lowercase Contracts commit SHA:
+
+```sh
+SOHA_CONSUMER_ROOT=/path/to/owned-consumers npm run check:consumers -- --require-all --contracts-sha <40-character-sha> --out /path/to/evidence/candidate.json
+```
+
+For an uncommitted candidate, first inspect `contractsRevision.sourceHash` in a
+`--dry-run --out /path/to/evidence/discovery.json` report, then pass both
+`--contracts-sha <40-character-sha>` and `--contracts-source-hash <64-character-sha256>`.
+The digest binds the recorded HEAD and changed/untracked source hashes, including
+deletions, entry types and normalized Git executable modes. Symlinks hash their link
+text without following external targets. A SHA alone requires a clean source checkout. Mismatched identities fail
+before any consumer command and are recorded in the output report. Store reports
+outside the source checkout and keep both inputs stable during execution.
+Dry-run reports have `status: "dry-run"`; they are discovery evidence, never a passed
+build. Omitted identity flags retain the existing local discovery behavior.
+
+The `contracts-ci` workflow can validate an explicit unpublished candidate without
+moving consumer pins or publishing anything:
+
+```sh
+gh workflow run ci.yml --repo opensoha/soha-contracts --ref <workflow-ref> -f contracts_sha=<40-character-sha> -f consumer_mode=pinned
+```
+
+Use a workflow revision and candidate containing this validation interface. The
+optional `contracts_sha` accepts only a full commit SHA; leaving it empty selects
+the workflow event's SHA, never a floating Contracts branch. Both verification and
+consumer jobs check out that SHA. CI retains the fixed consumer revision manifest
+unless `consumer_mode=latest` is explicitly selected. Each consumer job runs declared
+dependencies and candidate source separately: a declared failure still permits the
+candidate diagnostic, while either failure keeps the job failed. Step outcomes and
+separate `declared.json`/`candidate.json` artifacts remain visible. Setup failure or
+cancellation cannot count as a passed consumer run. This workflow has read-only
+repository permissions and does not load release secrets.
+
+Candidate source validation proves that exact source combination only. Declared
+validation tests the consumer's own dependency/lockfile. Published-package acceptance
+still requires checking the actual registry/proxy artifacts after publication.
+
+## Execution task callback credentials
+
+`ExecutionTask.callbackToken` is a callback capability, not ordinary task-view data.
+Normal task list/get and application, environment, runtime and release-board read
+views return the fixed non-secret string `[redacted]` when a callback is configured.
+This preserves the existing SDK string shape and configured-callback presence
+signal; the marker cannot be submitted as a callback credential. Historical empty
+values remain empty. Only authenticated runner claim/status paths return the real
+credential needed by that runner. Internal execution and callback validation keep
+the original value; task-view or configuration-secret read permission does not
+grant it.
+
+This documents the security projection within the existing v0.1.26 field shape.
+It adds no schema fields or SDK types and does not change the runner protocol.
+Clients must obtain runner credentials through the authorized runner flow rather
+than copying them from a user-facing task read.
 
 ## Compatibility Policy
 
@@ -208,48 +308,49 @@ properties, add required request properties, or remove enum values.
 
 ## Release Shape
 
-The stable TypeScript package name is `@opensoha/contracts`, and the stable Go
-module path is `github.com/opensoha/soha-contracts/gen/go/sohaapi`.
+The TypeScript package name remains `@opensoha/contracts`. The Go module is
+`github.com/opensoha/soha/contracts`, with the client in `gen/go/sohaapi`.
+Source metadata identifies `https://github.com/opensoha/soha`, directory
+`contracts`. SDK release tags use `contracts/v<package.json version>`; Root
+`v*` tags belong to Core and are ignored by the SDK version-sync gate.
 
-Release tags must be `v<package.json version>`. `npm test` runs
-`npm run check:version-sync`, which verifies `package.json`,
-`package-lock.json`, OpenAPI `info.version`, the Go module path, the Go client
-user agent version, and the GitHub release tag when the workflow runs from a
-tag.
+The current `0.2.0` metadata is a namespace-migration candidate, not a published release of
+the new Go namespace. Changing the Go module identity uses an intentional
+`0.x` minor release in B5, with coordinated consumer migration and public artifact
+verification. Historical released consumers retain their old module path until
+that migration. No `0.1.x` patch publication is implied by this source move.
 
-Release artifacts are prepared and verified with:
+From the Root workspace, prepare and verify local artifacts with:
 
 ```sh
-npm run release:artifacts
-npm run release:verify -- dist/release/opensoha-contracts-0.1.0.tgz
+npm run check:version-sync --workspace contracts
+npm run release:artifacts --workspace contracts
+npm run release:verify --workspace contracts -- dist/release/opensoha-contracts-0.2.0.tgz
 ```
 
-The command writes `dist/release/<npm-tarball>.tgz`, a matching
-`.sha256` checksum file, `dist/release/release-manifest.json`, a CycloneDX SBOM
-with its checksum, a provenance policy manifest with its checksum, and, when
-provided by CI, `dist/release/consumer-matrix.json`. `release:verify` checks
-the tarball checksum, manifest metadata, packed `package.json`, every exported
-package entrypoint, both OpenAPI artifact hashes, the SBOM identity and
-checksum, the provenance policy and checksum, and the consumer matrix summary.
-
-The tag workflow runs `npm test`, `npm pack --dry-run`, and the strict consumer
-matrix, then uses `NPM_TOKEN` to stage the npm tarball with provenance. A
-maintainer approves the stage on npmjs.com with 2FA. Dispatch the release
-workflow with the same tag and `publish_mode=recover` after approval. Recovery
-verifies the public npm package and Go module tag, attaches the release
-artifacts to GitHub, and verifies the downloaded tarball.
-
-The local release manifest records the provenance policy expected from the tag
-workflow. Verify the registry attestation's artifact digest and source revision
-after approval makes the package public.
-
-During private staging, consumers intentionally use sibling repository
-checkouts, `go.work` / `replace` entries, and `file:../soha-contracts` package
-dependencies instead of resolving this repository through anonymous GitHub
-module fetches or npm. After the repository is publicly readable and the npm
-package is published, released consumer modules can switch to a real
-`soha-contracts` version tag and the published npm package without changing SDK
-import paths.
+The verify argument is relative to `contracts/`. Artifact preparation writes an npm tarball, checksums, a release
+manifest, a CycloneDX SBOM and an expected provenance policy. Verification checks
+the tarball, package repository/directory, Go module identity, exported entries,
+OpenAPI hashes, SBOM and policy checksums, and any supplied consumer matrix.
+These checks prove local source/package consistency only.
+
+The expected SDK publisher is Root `.github/workflows/contracts-release.yml`,
+with the `contracts/v*` tag route and protected `release-contracts` environment.
+It uses OIDC trusted publishing and retains human npm 2FA stage approval. Enable
+the publisher only after the legacy publishers are disabled and drained;
+the historical `contracts/.github/workflows/release.yml` is retained but inactive,
+and Root `.github/workflows/release.yml` belongs to Core. A local provenance
+policy neither attests the package nor proves that this publisher exists.
+Actual registry provenance, source revision, npm availability and Go proxy/tag
+availability remain separate B5 release qualifications.
+
+Internal source development uses the Root npm workspace and `go.work`. External
+consumers must adopt the new namespace through a real version after its public
+release is verified; a local source replacement is not public availability proof.
+For `0.2.0`, migrate Go imports from `github.com/opensoha/soha-contracts` to
+`github.com/opensoha/soha/contracts` and pin `v0.2.0` only after public verification.
+The npm name stays `@opensoha/contracts`; the schema compatibility baseline and
+historical consumer revision pins remain unchanged.
 
 ## License
 
@@ -289,6 +390,9 @@ rendered manifests plus hooks to 2 MiB and values to 1 MiB, and are never logged
 
 Manifest tasks emitted by the controller-aware Core use `manifest_agent_v3.<clusterId>` and require the Agent summary capability `manifest.execution.v3`. New Agents also accept legacy `manifest_agent.<clusterId>` and `manifest_agent_v2.<clusterId>` tasks using the protected executor. Old Agents cannot claim the new provider kind; capability checks alone are not a substitute for this claim boundary during rolling upgrades.
 
+Plan-bound Manifest tasks additionally use `manifest_delivery_v1.<existingProvider>` and require `manifest.delivery-admission.v1`. Core validates the durable private operation and current Plan authority on every claim, then supplies `X-Soha-Manifest-Admission-Version: 1` in that claim response. Agent runners must reject a protected task without that exact response confirmation, including when polling an older Core with general runner credentials. A payload or a later task read is not admission proof. Direct providers remain local-only; protected Agent providers require the cluster Agent token. No fallback to an older provider is permitted. Known old application Plan tasks with `fieldManager` beginning `opensoha-manifest/` or a nonempty `initializationPlanId` are rejected on legacy providers, even with a header. These markers only deny execution; they never reconstruct or authorize Plan identity. Existing initialization and root-CR identity rules still apply to the underlying provider. These wire additions use existing SDK task and HTTP client APIs and remain source-compatible with SDK v0.1.26.
+
+
 Native YAML/CR writes and workload restart, scale, rollback and image changes use the existing request/response bodies under `/api/v1/platform/ownership-v2`, with the original route suffix. This endpoint family guarantees live external-owner checks for Operator, Argo CD, and Argo Rollouts resources and optimistic identity fencing; ownership conflicts return HTTP 409. Core must not fall back to older mutations after 404/405. Reads retain their existing routes.
 
 `resource/runtime` implements bounded WorkloadCronJob, Argo CD, and Argo Rollouts adapters shared by Direct and Agent. The frozen inventory, operation identity, current generation, resource UID/version, and child-resource evidence determine completion. Blue-green and Traefik canary delivery observe native Service revisions, weights, and complete AnalysisRun metric windows. Promotion only releases manual pauses; analysis failure and cancellation require confirmed stable traffic. Restoring desired configuration uses a new governed operation. Other CRs and traffic plugins are not inferred as supported from a generic Ready condition.

package/agent/agent-protocol.schema.json

@@ -153,7 +153,7 @@
             "providerId": { "type": "string" },
             "providerKind": {
               "type": "string",
-              "enum": ["internal", "hermes", "openclaw", "general", "openai", "anthropic", "openai-compatible", "deepseek", "qwen", "openrouter", "azure-openai", "gemini", "cohere"]
+              "enum": ["internal", "dsh", "hermes", "openclaw", "general", "openai", "anthropic", "openai-compatible", "deepseek", "qwen", "openrouter", "azure-openai", "gemini", "cohere"]
             },
             "status": {
               "type": "string",
@@ -370,7 +370,7 @@
             "providerId": { "type": "string" },
             "providerKind": {
               "type": "string",
-              "enum": ["internal", "hermes", "openclaw", "general", "openai", "anthropic", "openai-compatible", "deepseek", "qwen", "openrouter", "azure-openai", "gemini", "cohere"]
+              "enum": ["internal", "dsh", "hermes", "openclaw", "general", "openai", "anthropic", "openai-compatible", "deepseek", "qwen", "openrouter", "azure-openai", "gemini", "cohere"]
             },
             "status": {
               "type": "string",