Align Skill version selectors and Files error parameters

CONTRIBUTING.md

@@ -380,11 +380,12 @@ Resolve references inside the Session creation transaction, after the creation
 upsert establishes ownership. Lock referenced resources in a stable order; freeze
 the selected version, descriptive metadata and bytes together. Creation retries
 recover the recorded intent before reading mutable templates or Skill sources.
-Templates preserve omitted/default, latest and explicit version selectors. Session
-responses contain concrete versions; only validated installation metadata crosses
-the Runtime boundary. A supplied Session Skill list replaces the template list;
-omission inherits. Explicit null reference selectors and null list overrides remain
-unqualified and reject rather than silently changing selection.
+Templates preserve default, latest and explicit version selectors. An omitted or
+null reference version selects the default at Session creation and projects as
+`version: null` in Template responses. Session responses contain concrete versions;
+only validated installation metadata crosses the Runtime boundary. A supplied
+Session Skill list replaces the template list; omission inherits. Null list
+overrides remain unqualified and reject rather than silently changing selection.
 
 Inline and referenced Skill ZIPs use the same confidential initialization snapshot and installer.
 Core validates portable manifests and bounded regular-file archives, returns only

contracts/agents-api/README.md

@@ -14,6 +14,10 @@ Python **SDK** is a separate future dependency for business Team orchestration i
 Parsar, not the HTTP contract. Design rules live in
 [CONTRIBUTING.md](../../CONTRIBUTING.md#design-and-compatibility-requirements).
 
+The [resource selector and error qualification](resource-selector-semantics.md)
+records nullable Skill references and source Files not-found parameter fields,
+with official observations separated from Core acceptance.
+
 ## Implementation direction
 
 Keep the independent service, authentication, PostgreSQL/sqlc persistence,

contracts/agents-api/environment-templates.md

@@ -118,13 +118,15 @@ SDK 3.13.0 drops a single FileTypes tuple during multipart extraction before sen
 it. Use raw HTTP for a single ZIP with this fixed client; Core does not synthesize
 missing bytes or alter the pinned SDK.
 
-Templates preserve reference selectors: omission selects default at Session
+Templates preserve reference selectors: omission or null selects default at Session
 creation, `"latest"` selects latest, and a positive version string selects that
 version. A Session freezes tenant-authorized bytes and concrete version metadata
 in its creation transaction. Later source deletion, default changes or template
 updates cannot change that Session or its committed creation retry. A supplied
-Session Skill list replaces the template list; omission inherits. Explicit null
-reference versions and null list overrides are not qualified and reject.
+Session Skill list replaces the template list; omission inherits. Template
+responses include `version: null` for an unresolved default selector; resolved
+Session references retain a concrete version string. Null list overrides remain
+unqualified and reject. See [resource selector qualification](resource-selector-semantics.md).
 References return type/skill_id/version/name/description in Session metadata,
 while template responses retain unresolved selectors. Confidential bundle content
 never appears in these metadata responses. The common Runtime installation path
@@ -803,7 +805,7 @@ index under `~/.parsar/remediation/20260921/template-capabilities-design/`.
 
 The current upload profile accepts at most 500 regular files, 5 MiB compressed
 and 20 MiB expanded per bundle. These are qualified implementation limits, not
-published protocol maxima. Exact hosted error parity, null version selection,
+published protocol maxima. Exact hosted error parity,
 unversioned content selection, top-level metadata across version changes and
 last/default/latest deletion semantics remain recorded gaps. Current resource
 behavior selects default for unversioned content, preserves initial top-level

contracts/agents-api/operation-evidence.md

@@ -34,6 +34,7 @@ Repository paths below are relative to the inspected worktree; private evidence
 | K | `contracts/agents-api/environment-templates.md:94,764`: recorded fixed-SDK/raw/PostgreSQL Skill resource checks plus all-three-harness Docker reference workflows (Codex/Claude Kimi K3, MiniMax M2.7). Remote `~/.parsar/remediation/20260921/template-skill-references/`; local index `~/.parsar/remediation/20260921/template-capabilities-design/`. Covers upload, frozen template/Session resolution, native supporting files, source/template deletion, retry and cold continuation. Individual resource mutation cases not explicitly claimed by the summary remain DB-only or unspecified. |
 | I | `contracts/agents-api/environment-templates.md`: separate recorded initial-file (:589), env/setup/npm/Python (:621), inline-Skill (:657), system-package (:692), capability-directory, Plugin MCP (:241), composition (:327) and restricted-network (:523) qualification. Exact historical run roots are in each section. No combinatorial/full hosted parity inference. |
 | O | `services/agents-api/oauth-credentials.md:144`: recorded genuine Keycloak 26.7.4 PKCE grants, real TLS MCP and Kimi execution. Codex Basic client-auth initial/refresh/restart/replacement/revocation/delete; Claude POST initial/refresh. Trusted `none` profiles only; not MiniMax, hosted, arbitrary-provider or complete error equivalence. |
+| V | [Resource selector and error qualification](resource-selector-semantics.md); private September23 `skill-version-alignment/official/` and `files-error-alignment/official-probe.json`: owned Skill/Template/Session selector observations and seven missing File/cursor requests. Preserve each probe phase and distinguish actual hosted execution from metadata-only reads. |
 
 ## Per-operation evidence matrix
 
@@ -69,9 +70,9 @@ Paths in the appendix include `/v1`. SDK names here omit `client.`. `P` means pa
 | 26 | beta.agents.environments.retrieve | P: durable status, safe configured installation metadata | None located | D/I/K recorded native readiness and metadata | All lifecycle timing and installation inventory; configured metadata is not arbitrary workspace discovery |
 | 27 | beta.agents.environments.files.create | P: inline/source-file copy to qualified workspace | None located | F/D/K recorded real copy, hashes/consumption/retention | 50 MiB local bound, parent/path/overwrite/error/unknown-write semantics |
 | 28 | beta.agents.environments.files.list | P: direct regular-file directory, opaque cursor | None located | F/D/K recorded live workspace listing | 1,024-entry prefilter bound; no recursion/symlinks; exact defaults/path/errors/mutation invalidation unknown |
-| 29 | beta.agents.environments.templates.create | P: reusable network/files/env/setup/packages/Skills/Plugins/capability config, 201 | R `template-create` | C DB; I/K recorded real frozen-reference initialization | Restricted forms and unqualified combinations; complete hosted initialization semantics |
-| 30 | beta.agents.environments.templates.retrieve | P: safe resource read | R `template-read`, deleted owned read | C DB; I/K recorded reference workflow | Full field/default/redaction parity; no live-secret projection inference |
-| 31 | beta.agents.environments.templates.update | P: field replacement/null clearing, empty timestamp touch | R `template-patch`, `template-null`, `template-noop` | C DB no-op; I/K recorded frozen Session behavior | Referenced Session files/env/setup/packages overrides reject; null network/list/Skill-version remains unresolved |
+| 29 | beta.agents.environments.templates.create | P: reusable network/files/env/setup/packages/Skills/Plugins/capability config, 201 | R `template-create`; V nullable Skill selector projection | C DB; I/K recorded real frozen-reference initialization | Restricted forms and unqualified combinations; complete hosted initialization semantics |
+| 30 | beta.agents.environments.templates.retrieve | P: safe resource read | R `template-read`, deleted owned read; V nullable Skill selector projection | C DB; I/K recorded reference workflow | Full field/default/redaction parity; no live-secret projection inference |
+| 31 | beta.agents.environments.templates.update | P: field replacement/null clearing, empty timestamp touch | R `template-patch`, `template-null`, `template-noop`; V nullable Skill selector projection | C DB no-op; I/K recorded frozen Session behavior | Referenced Session files/env/setup/packages overrides reject; null network/list/Skill-version remains unresolved |
 | 32 | beta.agents.environments.templates.list | P: scoped cursor list | R `template-list-empty-scoped` | Recorded resource DB checks; no positive C list replay | Full nonempty/multipage/mutation/default/error parity |
 | 33 | beta.agents.environments.templates.delete | P: delete resource, preserve committed Session snapshot | R `cleanup` at Template path, post-delete read | C DB; K recorded live deletion then continuation | Concurrent references/delete and exact errors |
 | 34 | beta.agents.vaults.create | P: tenant resource, 201 | R `vault-create`, `vault-empty-token-fixture` | C DB; O recorded MCP attachment workflow | Archive lifecycle, full defaults and selection parity |
@@ -84,27 +85,27 @@ Paths in the appendix include `/v1`. SDK names here omit `client.`. `P` means pa
 | 41 | beta.agents.vaults.credentials.list | P: safe scoped metadata/status list | R `credential-list` | C DB mixed list/rejected-write/restart; O recorded resource checks | Complete status-filter/page limits/archive behavior |
 | 42 | beta.agents.vaults.credentials.delete | P: encrypted resource deletion and dispatch denial | R `cleanup` at Credential paths | C DB; O recorded live Codex refusal after deletion | Cannot recall already-delivered token; exact hosted withdrawal/error timing |
 | 43 | files.create | P: immutable multipart purpose=user_data | None located | F recorded DB upload; D/K recorded native source consumption | Other purposes/expires_after unsupported, 512 MiB local size vs pinned 512 MB wording; full multipart/errors |
-| 44 | files.retrieve | P: project-owned metadata | E missing-ID 404 only | F recorded DB workflow; C missing-ID DB replay | Successful official shape/default/status purpose union and error param unknown |
-| 45 | files.list | P: purpose filter, default/max 10,000, cursor list | None located | F recorded actual PostgreSQL SDK/raw pages/autocontinuation/restart/isolation | Exact official ordering/cursor/error/concurrent-mutation semantics |
-| 46 | files.delete | P: transactional metadata/body unlink | None located | F recorded DB deletion; D/K recorded retained workspace copies | Admitted immutable read may complete after deletion; hosted concurrency/retention unknown |
-| 47 | files.content | P: immutable binary stream | None located | F recorded DB; D/K recorded source workflow | Range/header/partial-transfer and exact errors; retrieve_content is same HTTP operation |
-| 48 | skills.create | P: encrypted bounded directory/ZIP bundle | None located | K recorded DB resources and Live three-harness upload/reference | Fixed SDK single-tuple multipart issue; 500 files/5 MiB compressed/20 MiB expanded local limits |
-| 49 | skills.retrieve | P: safe top-level metadata | E missing-ID 404 only | K recorded DB resource checks; C missing-ID DB replay | Metadata evolution across versions is local policy, successful official semantics unknown |
-| 50 | skills.update | P: change default version only | None located | K recorded DB resources; frozen Session behavior in Live reference workflow | Default/latest/explicit/null semantics and top-level metadata evolution unknown |
+| 44 | files.retrieve | P: project-owned metadata | E/V missing-ID404 param=id; V fixedSDK exception | F recorded DB workflow; V actual HTTP/PG foreign==missing | Successful official shape/default/status purpose union; other errors |
+| 45 | files.list | P: purpose filter, default/max 10,000, cursor list | Q explicit-order error; V missing-after404 param=after | F recorded actual PostgreSQL SDK/raw pages/restart/isolation; V missing cursor | Exact successful official ordering/concurrent-mutation and other query semantics |
+| 46 | files.delete | P: transactional metadata/body unlink | V random nonexistent ID404 param=id | F recorded DB deletion; V actualHTTP/PG foreign delete denial preserves bytes; D/K retained workspace copies | Admitted immutable read may complete after deletion; hosted concurrency/retention unknown |
+| 47 | files.content | P: immutable binary stream | V missing-ID404 param=id | F recorded DB; V actualHTTP/PG missing/foreign content denial; D/K source workflow | Range/header/partial-transfer and other errors; retrieve_content is same HTTP operation |
+| 48 | skills.create | P: encrypted bounded directory/ZIP bundle | V successful owned directory uploads | K recorded DB resources and Live three-harness upload/reference | Fixed SDK single-tuple multipart issue; local upload limits remain partial |
+| 49 | skills.retrieve | P: safe top-level metadata | E missing-ID404; V default1/latest2 metadata | K recorded DB checks; C missing-ID DB replay | Top-level metadata evolution across differing manifests remains unqualified |
+| 50 | skills.update | P: change default version only | V default1→2 mutation; preexisting Session selectors unchanged | K recorded DB resources; frozen Session behavior in Live reference workflow | Top-level metadata evolution and error cases remain unqualified |
 | 51 | skills.list | P: scoped resource list | None located | K recorded DB resources; no model needed | Current documentation minimum zero is only a lead; fixed/common 1–100 implementation and exact official behavior require evidence |
 | 52 | skills.delete | P: remove owned source, retain committed Session content | None located | K recorded DB and Live source deletion/continuation | Exact hosted deletion/idempotence/default/latest semantics |
 | 53 | skills.content.retrieve | P: unversioned content selects default | None located | K recorded DB resource checks | Default-vs-latest unversioned selection unverified; headers/errors |
-| 54 | skills.versions.create | P: immutable increasing version; optional default change | None located | K recorded DB resource checks | Numbering/default/top-level metadata/error/null semantics; same upload limits |
-| 55 | skills.versions.retrieve | P: owned immutable version metadata | None located | K recorded DB resource checks and Live concrete Session freeze | Selector/metadata/error parity; reference version:null rejects locally |
-| 56 | skills.versions.list | P: scoped version cursor list | None located | K recorded DB resource checks | Exact ordering/cursors/zero/default/max limits and concurrent version mutation |
+| 54 | skills.versions.create | P: immutable increasing version; optional default change | V second version default=false preserves default1/latest2 | K recorded DB resources | Broader numbering/default/top-level metadata/error/null semantics; upload limits |
+| 55 | skills.versions.retrieve | P: owned immutable version metadata | V immediate version1 read404, bounded delayed read200 | K recorded DB resources and Live concrete Session freeze | Visibility timing is observational; full selector/metadata/error parity unqualified |
+| 56 | skills.versions.list | P: scoped version cursor list | V delayed owned list contains created versions | K recorded DB resource checks | Exact ordering/cursors/zero/default/max limits and concurrent version mutation |
 | 57 | skills.versions.delete | P: nondefault deletion; default deletion rejects | None located | K recorded DB resources; exact per-variant live case not claimed | Last/default/latest deletion behavior and non-reused numbers are unverified local choices |
 | 58 | skills.versions.content.retrieve | P: decrypt/read owned concrete bundle | None located | K recorded DB checks; Live native frozen supporting files | Content headers/errors and source deletion/read races; consumption does not prove download wire parity |
 
 ## Remaining gaps without task ordering
 
 1. **Public generic semantics:** sampled create/event/envelope/error/no-op corrections are merged. Resource-by-resource omissions/null/default/error params, malformed queries, list caps, unknown/empty query handling, concurrent mutation and deletion require separate evidence. Metadata U+0000 remains an implementation-validation question from the prior audit, not a newly reproduced result here.
 2. **Session differences:** The Session admission batch removes idle `none` creation and empty metadata update. Local durable creation idempotency remains an explicit difference. Whitespace-only input succeeds officially but is rejected by the existing Core message validator; this newly observed difference is queued separately. Session agent updates, newer Environment shapes and root Item turn_id are baseline-upgrade questions.
-3. **Template/Skill composition:** referenced files/env/setup/packages override rejection is a known implementation gap; exact merge/replacement/null semantics need evidence. Null reference versions/null override lists, unversioned Skill content, top-level version metadata and last/default/latest deletion remain unresolved.
+3. **Template/Skill composition:** referenced files/env/setup/packages override rejection is a known implementation gap; exact merge/replacement/null semantics need evidence. Null override lists, unversioned Skill content, top-level version metadata and last/default/latest deletion remain unresolved.
 4. **Execution coverage:** use T's qualified matrix, not a blanket missing-image/structured-output claim. MiniMax functions/service MCP, optional tool combinations, unsupported images/placements and broader native lifecycle are explicit restrictions. PTC omission retains approved native behavior; Claude/MiniMax public Usage remains null; child settlement cadence/native close limits remain visible. No second executor/model loop or guessed counters are justified.
 5. **Workspace and resources:** live Files bounds, symlink/path/cursor choices, artifact overwrite/republishing/headers/cancellation edges, full Environment metadata/lifecycle and Vault archive/in-flight-token semantics remain partial or unknown. Retired Core-managed E2B acceptance cannot qualify current user enrollment.