Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@ Released under the [MIT License](LICENSE), matching [`main`](https://github.com/

## Federation source contracts

Versioned [source contracts](schemas/) describe repository roles and file references. The [read-only checker](tools/architecture_conformance.py) checks declared repository owners and visibility labels, required local paths, reference formats, and restrictions on scientific-status fields.
Versioned [source contracts](schemas/) state the canonical producer form of repository roles and file references; acceptance is defined by the [standard-library validators](tools/contract_validation.py) (see [producer form and reader acceptance](docs/ARCHITECTURE_CONFORMANCE.md#producer-form-and-reader-acceptance)). The [read-only checker](tools/architecture_conformance.py) checks declared repository owners and visibility labels, required local paths, reference formats, and restrictions on scientific-status fields.

These structural checks do not verify actual repository versions, file contents, live permissions or mathematical correctness.

Expand Down
52 changes: 52 additions & 0 deletions docs/ARCHITECTURE_CONFORMANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,55 @@ The C146 audit's default-layout run at main `3bcf0e34b15dc38270b163263d62b690884
`WORKSPACE_SNAPSHOT.json` and per-repository `SOURCE_MANIFEST.json` are optional inputs to this checker. Their commit/hash fields receive syntax and structure checks, not comparison with the actual checkouts or payload bytes. The [example snapshot](../examples/workspace_snapshot.json) contains repeated-digit placeholder commits, not reproducible pins; the [conformance tests](../tests/test_architecture_conformance.py) use synthetic directories and an authority-map fixture. Passing those fixtures does not verify a real federation cut. Even structurally valid records can describe the wrong local cut without this checker detecting that mismatch.

Unknown schema major versions, mutable refs, sandbox leakage, scientific-status fields in public registry artifact rows, and architecture ownership of promotion fields fail closed. These refusals do not supply the missing checkout authentication. Existing sandbox path/catalog exclusions and publication boundaries remain unchanged; do not fetch exploratory payloads to manufacture a conformance pass.

## Producer form and reader acceptance

The four schemas in [schemas/](../schemas/) state the **canonical producer
form** of a contract document; the validators in
[tools/contract_validation.py](../tools/contract_validation.py) define
**acceptance**. Decision record: [issue 15](https://github.com/d6g8k5htny-coder/meta-framework/issues/15)
(finding 6129626684; decision 6133399141 as corrected by 6133564511).

- A canonical producer document satisfies the schema profile (every key the
schema lists in `required`, with its declared type; a declared property may
be `null` only where its declared type includes `null`, today
`runtime_package` only; properties the schemas leave unconstrained under
`additionalProperties: true` are not affected by this rule) **and** the
Python semantic and safety checks in the relevant mode: source references
default to `public=True`, source manifests always require public sources
(they take no mode parameter), repository roles and workspace snapshots
accept the private `sandbox` repository by name. Schema validation alone is
insufficient: the schemas do not express the path, whitespace, uniqueness,
repository-set and public-mode rules that the validators apply. The five
files under [examples/](../examples/) are the verified canonical instances.
- Readers apply exactly two compatibility allowances beyond the canonical
form. `schema_version` may be a major-1 decimal spelling that the validator
accepts: the grammar is `^([0-9]+)\.([0-9]+)$` with the major part equal to
`1` after integer conversion (`1.1`, `1.10`, and the tolerated leading-zero
forms `01.0` and `1.00`; `2.0`, `1`, `1.0.0` and non-strings are refused).
The allowance covers the established spellings within the implementation's
limits; a digit string beyond Python's integer-conversion limit raises an
ordinary `ValueError` from the unchanged reader rather than `ContractError`,
a pre-existing edge recorded here, not blessed. A repository role may omit
`runtime_package`. An omitted key is never synthesized:
`validate_repository_role` returns a shallow copy whose key presence mirrors
the input, so consumers read it with `.get`.
- Nothing else the implementation happens to accept is part of the contract.
Known reader looseness outside the two allowances (for example the string
coercion of integer-valued hex fields) is a defect for a reviewed repair, not
an allowance. Equally, refusing the leading-zero spellings or requiring
`runtime_package` at read time would be a breaking acceptance change and is
made only deliberately, never by drift.
- The schemas are not a substitute reader: a tool that validates incoming
documents with them alone refuses documents the project accepts and accepts
documents the project refuses.

[tests/test_contract_compatibility.py](../tests/test_contract_compatibility.py)
pins both sides: the version grammar and omission semantics of the validators,
the canonical form of the examples including the nested manifest `files[]` and
snapshot `repositories[]` records (string hex identities, which the reader
would otherwise coerce with `str()`), and the literal schema facets (`const`
`"1.0"` in all five `schema_version` declarations; `runtime_package` required
with type `["string","null"]`). A change to either side fails a named test and
reopens this record. None of this changes scientific status, sandbox
exclusions or publication boundaries.
Loading
Loading