Add federation and transport bindings working drafts by marcschier · Pull Request #571 · xregistry/spec

marcschier · 2026-09-10T17:52:58Z

Current-main refresh

Merged xregistry/spec:main at 8e8c6e0f12570efcc69782c8e9e672bc50ae727f in 24bc0e20 with DCO sign-off. This includes #725, #727, #728, #731, #732, #733 and #734.

The seven upstream changes are merged without changing any workingdrafts file. The merged #568 Events and distinct Resource/Version model remain intact. The authored diff stays in workingdrafts, plus pytest.ini, tools/Makefile and tools/test_samples.py. The schema generator, fail-fast model checker and renamed site-dispatch workflow match upstream main. All 1,179 tests pass using mainline dependencies; the draft's documented projection limitations are not hidden by importing an enhanced generator from another unmerged PR.

The existing PR grouping is preserved. Earlier commit-specific results below are historical; current hosted checks apply to the refreshed head.

Proposed Changes

This PR proposes working-draft specifications for read-only xRegistry
federation. A Registry combines local Resources with cataloged sources
using HTTP, OCI, Git, File or OPC UA. Views identify whether the consumer or
producer performs resolution; absence of the signal defaults to the consumer.
Producers can serve a combined view on demand or publish it as stored files.
The drafts also define OCI packaging and a directory mapping that preserves
existing file layouts.

Specifications

Start with Registry of Registries and Federation, then use the binding comparison to choose the relevant binding.

Specification	Description
Registry of Registries	Catalog entries describing Registries, access methods and relationships.
Federation	Producer/consumer resolution, local shadows and source selection, with a worked example of label selection after shadowing.
Directory Mapping	Map existing files to a Registry. Includes a complete one-file walkthrough with every metadata file, matching hashes and expected read results.
OCI Binding	Package and read Registry snapshots through OCI Distribution, with artifact-content and resolution-sequence diagrams.
HTTP Federation	Access source Registries through the existing HTTP API, including pagination and live-read consistency.
Git Binding	Read directory mappings from a pinned Git commit using stored object bytes.
File Binding	Read mappings or OCI layouts on local storage or OS-mounted file shares, with containment and integrity checks.
OPC UA Binding	Native Registry access, Events, distinct Resource/Version nodes, reference resolution and document transfer over OPC UA.
OpenUSD Alignment	Clarify the distinction between local aliases and remote document links in the existing draft.

Models, schemas, samples and tests are supporting material, not the
starting point for review. The complete examples are readable in the specs
without running the test suite. These remain unreleased working drafts.

Enhanced schema-generator fixes are handled separately in #574 and #724. This PR uses the mainline generator and does not depend on either unmerged implementation.

Release Note

Added Registry-of-Registries and federation working drafts, native access
bindings, resolution-owner signaling, OCI packaging, directory mapping and
complete worked examples.

Define the native OPC UA event type mapping, interaction semantics, notifier topology, subscriptions, filtering, and optional conformance units for the xRegistry Events working draft. Signed-off-by: Marc Schier <marcschier@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5

Document the normative errata applied to the xRegistry Events draft, define observable interaction boundaries for domain methods, Writes and FileTransfer, and constrain notifier delivery guarantees during deletion. Signed-off-by: Marc Schier <marcschier@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5

Require FileTransfer writes to stage document bytes and update Version Epoch and ModifiedAt only when a successful Close commits byte-different content. Keep clean, aborted, and byte-identical closes side-effect free. Signed-off-by: Marc Schier <marcschier@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5

Address review feedback by distinguishing domain resource names, the inseparable Resource/first-Version create, Version labels, and the first-class Resource Meta entity. Signed-off-by: Marc Schier <marcschier@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5

Signed-off-by: Marc Schier <marcschier@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5

Define the hub-compatible Registry domain, shared federation contract, portable document format, and native OCI, HTTP, Git, File and OPC UA bindings. Include derived schemas, executable conformance examples, generator corrections, and repository integration. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Record local Registry draft edits, including updated model versions and removal of the hub-compatibility and source-crosswalk sections. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Restore the primer and CloudEvents schema artifacts to the PR baseline as requested in xregistry#571. Track future primer work in xregistry#572 and verified generator bugs in xregistry#573 with separate PR xregistry#574. Align the authored 1.0-rc1 draft status and tests and remove a stale TOC link and trailing whitespace. Signed-off-by: Marc Schier <marcschier@hotmail.com>

The clean CI dependency set omitted jsonschema's optional URI-reference validator, silently accepting malformed relationship targets. Install the non-GPL format extra and preserve the existing rejection assertions. Validated 395 focused tests in a clean environment. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Define client/server hosting, local Resource shadowing, ordered source selection and diagrams. Move the portable document format beside its bindings, add binding motivations, remove crosswalks and legacy xregurl wording, and rewrite semicolon-delimited prose. Fix all four code-review defects with regressions. Keep all released schema artifact changes in xregistry#574 and out of xregistry#571. Leave review threads unresolved as requested. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Address xregistry#571 feedback by renaming the format document to mapping.md, permitting root-relative metadata and document paths throughout the selected directory, and retaining integrity, containment and Resource identity rules. Add File/Git regression coverage for unchanged existing files, Unicode names and shared document references. Keep registry.json unchanged while documenting dotfile tradeoffs in the review reply. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Address the editorial review and current xregistry#571 threads with a complete byte-accurate mapping walkthrough, post-shadow selection example, binding comparison and OCI diagrams. Clarify catalog and error terminology, simplify security prose, and align mapping helper/sample names. Preserve conformance-section placement and released artifact exclusions. Validate the examples and full 1164-test suite. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Link OCI advertisement handling to Federation, replace filesystem stem jargon with names, consistently describe directory mappings, and explain NAS or file-share access through OS-mounted paths without changing URI authority policy. Signed-off-by: Marc Schier <marcschier@hotmail.com>

marcschier · 2026-09-11T11:57:20Z

(keep this feedback as-is, do not do anything yet!)

Maybe we should move the bindings files in this PR under federation/bindings, and only retain opcua.md here. We can later change http-federation.md and move its contents into http.md (like opcua.md containing federation), while the git, oci, file, mapping are explicitly for federation and not useful outside?

Signed-off-by: Marc Schier <marcschier@hotmail.com>

Move the existing draft helpers and conformance tests into bundle-local tools directories. Use qualified imports and shared pytest discovery, and update the documented commands and links. Preserve helper behavior, model/schema data and all existing test cases; leave pending implementation changes out of this commit. Signed-off-by: Marc Schier <marcschier@hotmail.com>

…tests Snapshot of uncommitted working-tree state taken before merging origin/main and upstream/main, so nothing is lost during conflict resolution. Undo with: git reset --soft HEAD~1 Signed-off-by: Marc Schier <marcschier@hotmail.com>

Completes the interrupted pull. Conflicts were confined to the tools-colocation refactor, where the local snapshot and the pushed commit expressed the same change differently. Kept the bundle-relative paths, which match the refactor goal and resolve to the same locations as the root-absolute form, together with the wider federation imports and the OpenUSD tooling row. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Brings in the upstream tooling update, CloudEvents sample semantics and misc issue fixes. The only conflict was tools/Makefile. Kept upstream target ordering, its success echo and every auto-merged change, together with our broader find-based schema-dir guard, the untracked-schema check, the samplescheck target and the registry makeschema lines that upstream does not carry. Kept our curated spellcheck and ticks file lists rather than upstream find-based sweep: the sweep flags PowerShell line-continuation backticks inside a fenced code block in workingdrafts/models/registry/schemas/README.md, which our lists deliberately exclude. Signed-off-by: Marc Schier <marcschier@hotmail.com>

…emas CI failed on testpython and would have failed on links next. A named Avro type reference resolves only in its bare form, but handle_item assigned the wrapped {"type": "<name>"} mapping entry to array items while the map branch already unwrapped, so every array of opaque items was an unparseable schema. Regenerated artifacts; the schema/ outputs were additionally stale at the merge head, independently of this fix. Superseded the JSON Structure assertion that walked into the AMQP properties section, which is now a deliberately opaque declaration record, and kept the dashed-name altnames check on the still-structured header section. Reworded descriptive uses of RFC2119 keywords that the link checker flagged, capitalising only the two genuinely normative sentences. Signed-off-by: Marc Schier <marcschier@hotmail.com>

These tests asserted the natural-language wording of spec Markdown - string containment on sentences, and in one case the exact whitespace of a table row - so ordinary editorial rewording broke them without any contract changing. The OpenUSD file stated the intent outright: "These tests guard normative prose". Only consistency between files stays in scope, so the cross-file checks remain: include-pointer resolution, generator expansion, model-to-artifact agreement and the sample/example suites. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Move the "before resolving an advertisement" qualifier behind the obligation so the sentence opens with the actor and the MUST. The requirement, its trigger and its scope are unchanged. Verified with Lingity architecture-review 1.3.0 against the pre-edit bytes: protected_delta equivalent, with zero missing, added, specified and unresolved elements. HRI 7.76 -> 7.85, defects 321 -> 320, high-severity 17 -> 17, lowest substantive block 79.01 unchanged. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Re-segment nine over-long or multi-clause sentences in the OPC UA binding. Each edit keeps the subject that the source already stated and introduces no new actor, so no obligation changes hands. Changes: split the Abstract and Scope colon-sentences; split the information-model sentence into one sentence per type; turn the baseline operation model, the Method signature inventory, the registry read sequence and the read-only and writable conformance criteria into lists; separate the locking purpose clause; and lead the ignore-semantics requirement with its premise instead of a "Because" subordinate clause. Lingity architecture-review 1.3.0, measured against the pre-edit bytes: high severity 115 -> 95 violations 136 -> 113 blocks below 85 20 -> 16 lowest block 75.38 -> 76.10 defects 1000 -> 979 document HRI 0.14 -> 0.15 LING-SENTENCE-001 7 -> 3 LING-CLAUSE-001 9 -> 6 LING-LIST-001 25 -> 21 LING-ACTION-001 22 -> 19 LING-NOMINALIZATION-001 13 -> 10 LING-PUNCTUATION-001 12 -> 10 protected_delta reports specified 0, so no previously unnamed actor was named. It reports disposition unresolved with missing 26 and added 23. Those are re-segmentation artifacts: the claim extractor keys a claim on a word-bag of its whole sentence, so splitting one sentence retires the long claim and registers the shorter ones. Each pair was checked by hand and carries the same obligation, actor and modality. Four candidate edits were reverted because the extractor lost an actor or modality binding: the inverse import list, the resource replacement sequence, the export-capable criteria and the client conformance criteria. Those paragraphs keep their original wording. The document floor of HRI 85 remains unreachable. The residual findings are dominated by the mandated RFC2119 boilerplate, by Markdown link parentheses counted as parentheticals, and by rules that are satisfied only by naming an actor this specification deliberately leaves unstated. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Keep only the wording edits whose Lingity protected_delta stays equivalent with zero missing, added, specified and unresolved elements, and whose replacement is genuinely better English. Lingity architecture-review 1.3.0 is unchanged by these edits: HRI 3.30, 449 defects, 49 high-severity findings, 11 substantive blocks below the 85 floor. The remaining defects are dominated by LING-PASSIVE-001, LING-ACTOR-001 and LING-AGENCY-001, which require naming an actor the specification does not name. Every such rewrite trips protected_delta, so the floor is unreachable without changing normative claims. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Apply nine editor-approved readability repairs from an interactive Lingity editing session. Every split keeps the subject the source already stated, and causal and ordering cues are preserved with an equivalent connective rather than dropped. Main repairs: - Turn the four-way "discoverable / verifiable / versioned / federatable" enumeration into a list, restating the subject so it stays bound. - Split the Abstract at the em-dash and drop "in order to". The enabling verb "allows" is kept, so the registry is not newly asserted to perform storage, discovery and federation itself. - Split the asset-resolution procedure, keeping the validate-then-retrieve ordering explicit with "only after that validation". - Split the xid definition so the RFC 3986 constraints form their own sentence with xRegistry as the stated subject. - Separate the two digest obligations into one sentence each. - Split six further run-on sentences in 1.2, 1.3, 4.4, 5.3, 5.5 and 5.6. Lingity architecture-review 1.3.0, measured against the pre-edit bytes: document HRI 3.30 -> 4.21 violations 61 -> 32 defects 449 -> 419 high severity 49 -> 28 blocks below 85 11 -> 3 lowest block 73.07 -> 80.97 The comparison against the original reports missing 22 and added 29. Those are re-segmentation artifacts: the claim extractor keys a claim on a word-bag of its whole sentence, so splitting one sentence retires the long claim and registers the shorter ones. Each pair was checked by hand. It reports specified 1, "actor specified: use assigned to 'consumer'", from splitting "MUST verify it and MUST NOT use ..." into two sentences. The actor is the same sentence's own subject, "A Consumer that has retrieved an artifact for which a digest is declared", so no obligation changed holder. This delta was explicitly authorized by the editor. Twenty-eight findings are retained by editor decision. They are dominated by the mandated RFC 2119 boilerplate, by Markdown link anchors counted as hyphenated compounds or parentheticals, by OPC, UA and USD read as undefined acronyms, and by defined domain terms such as "dependency closure". The HRI 85 floor is not reachable on a normative specification without altering what it requires. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Name the actors consistently. The specification placed obligations on Consumer, Producer and implementation without defining any of them, and spelled the same role two ways. - Add 2.2.4 defining Consumer as the party that retrieves and composes artifacts and Producer as the party that publishes them, and state that capitalized role names denote defined roles. - Normalize the nine lowercase "consumer" uses to Consumer. No genuinely generic use existed; the split ran along normative versus narrative text without ever being declared. - Rename the four "publisher" uses to Producer. The editor confirmed these name the same party as the Producer of 5.1.1, which previously appeared in that subsection alone. - Change the single "client" in 1.2 to Consumer. Give three obligations an actor, each supported by its surrounding text: - 4.1 "a collision MUST be rejected" -> "An implementation MUST reject a case-insensitive collision", matching the parallel rule later in the same section. - 4.5.5 "it MUST be published" -> "a Producer MUST publish it". - 5.1.1 "Inconsistent bindings MUST be -> "A Producer MUST reject rejected" inconsistent bindings". Lingity architecture-review 1.3.0, measured against the pre-edit bytes: LING-AGENCY-001 12 -> 9 LING-PASSIVE-001 68 -> 65 actor-rule total 104 -> 94 defects 419 -> 416 blocks 240 -> 244 mean block HRI 97.25 -> 97.33 blocks scoring 100 97 -> 99 The composite document score moved 4.21 -> 4.09 while every block measure improved. That number is dominated by the 28 unchanged high-severity residue findings and does not track this work. Three rules rose by one each: REDUNDANCY from repeating the role names, and ABBREVIATION and COMPOUND-DEPTH from the new heading and its anchor. protected_delta reports specified 2, "reject assigned to 'implementation'" and "reject assigned to 'producer'". Both were authorized explicitly, and both actors come from the surrounding text rather than from invention. Three obligations keep no actor because the source does not determine one, and they remain open rather than resolved: a usdassetid MUST NOT be derived from the artifact's bytes, an xid MUST NOT be used as an asset identifier, and metadata acquisition MUST be explicitly authorized. The inherited xRegistry 2.1 boilerplate is left untouched. Signed-off-by: Marc Schier <marcschier@hotmail.com>

marcschier · 2026-09-22T07:33:00Z

Added three OpenUSD readability commits to this PR (3db72c4, b5c9abc, cf9f4a0), touching only workingdrafts/models/openusd/spec.md.

Readability, measured with the local Lingity architecture-review 1.3.0 policy against the pre-edit bytes:

Measure	Before	After
Document HRI	3.30	4.09
Policy violations	61	32
Defects	449	416
High severity	49	28
Blocks below the 85 floor	11	3
Lowest substantive block	73.07	80.97

Principal changes: split the Abstract, the xid definition, the asset-resolution procedure and several run-on requirement sentences, each keeping the subject the source already stated and preserving causal and ordering cues.

Actor naming. The spec placed obligations on Consumer, Producer and implementation without defining any of them, and spelled the same role two ways (Consumer/consumer 23/9, Producer vs publisher). Added §2.2.4 defining Consumer and Producer, normalized the spellings, and gave three previously actorless MUSTs their actor:

§	Before	After
4.1	"a collision MUST be rejected"	"An implementation MUST reject a case-insensitive collision"
4.5.5	"it MUST be published"	"a Producer MUST publish it"
5.1.1	"Inconsistent bindings MUST be rejected"	"A Producer MUST reject inconsistent bindings"

LING-AGENCY-001 12 → 9, LING-PASSIVE-001 68 → 65.

Still open, not resolved — three obligations whose actor the source does not determine: §1.3 "a usdassetid MUST NOT be derived from the artifact's bytes", §1.3 "an xid … MUST NOT be used as an asset identifier", and §5.1.1 "Metadata acquisition … MUST be explicitly authorized". These were deliberately left rather than guessed.

The document still does not meet the policy floor (HRI 4.09 against 85). The residual findings are dominated by the mandated RFC 2119 boilerplate, Markdown link anchors counted as compounds/parentheticals, OPC/UA/USD read as undefined acronyms, and defined domain terms such as "dependency closure".

Validated: tools/verify.py . succeeded; full suite 1,243 passed; git diff --check clean; all three commits signed off.

Undo every change outside workingdrafts, keeping only the tools changes that workingdrafts content actually needs, and make the workingdrafts schemas generate with the mainline tools/schema-generator.py. Reverted to upstream: - cloudevents, endpoint, message, schema and pagination specs, models and generated schemas. The endpoint and message model compaction and the regenerated core schemas belong to the core specification, not here. - docs/implementation-feedback.md, which documents those core model fixes. - tools/schema-generator.py, tools/test_schema_generator.py and tools/test_verify.py. - tools/requirements.txt. The jsonschema[format-nongpl] extra asserted absolute-URI format on self, which Core mandates be the relative "#JSON-POINTER" form in document view. - Deleted tools/test_implementation_discovery_regressions.py, tools/test_implementation_model_regressions.py and tools/test_review_regressions.py. All three test core tooling and reference no workingdrafts content. - Deleted two stray report.*.json profiling dumps. Kept as workingdrafts-scoped tools changes: - pytest.ini, which exists to discover workingdrafts tests, now also putting tools on the path so the mainline tool tests still import. - tools/Makefile, for the workingdrafts spellcheck and back-tick lists, the schemas directory discovery and the registry makeschema targets. Upstream's find-based sweep breaks on a workingdrafts README. - tools/test_samples.py, which adds workingdrafts sample discovery. Workingdrafts changes required by the mainline generator: - Regenerated the registry schemas. The mainline generator does not emit the Resource meta and versions envelope, for any model; upstream's own cloudevents schema has the same thinner shape. - Dropped document-schema.avsc. The mainline generator emits an empty items type for the federationprofiles and relationships arrays of objects, producing an Avro schema that does not parse. The other three outputs are valid, so only Avro is removed, along with its makeschema line and its README references. - Removed versionsurl and versionscount from the three catalog samples and the test fixture where versions is inlined. Mainline models these as mutually exclusive, and 639 core samples inline versions alone. - Removed the generated-schema assertions that require shapes the mainline generator cannot produce, and the relationship target format case that depended on the format extra. tools/verify.py succeeds and the full suite passes, 1179 tests. Signed-off-by: Marc Schier <marcschier@hotmail.com>

The all target was widened to every schemas directory found on disk, which also covered workingdrafts/models/registry/schemas. That check is core tooling rather than workingdrafts content, and CI failed on it because the committed registry schemas were generated on a different host than the one that regenerates them. Restore the upstream "*/schemas" glob and drop the untracked-file guard added alongside it. The registry makeschema targets stay, so the schemas are still regenerated; they are simply not diff-checked, exactly as upstream treats every schemas directory outside its own glob. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Apply editor-approved Lingity repairs to file.md, git.md, http-federation.md and mapping.md. Every change was an explicit editor decision; no actor or fact was invented. Structure: split or bulleted the long inline enumerations that carried the LIST and PUNCTUATION findings, including the mapping format's storage-metadata omissions, the git blob-read prohibitions, the HTTP federation offline-example scenarios and the shared fixture contents. Responsibility: gave an actor to obligations whose grammatical subject was a thing, using only parties the surrounding text already names. file.md check/guess -> resolver, infer -> implementation, read -> consumers git.md peel/record/report -> resolver, read -> consumers http-federation.md mistake/report/use -> resolver mapping.md reject -> consumer, allocate/copy -> producer, decode/preserve -> consumers Also expanded UNC and object ID on first use, and corrected one pronoun in http-federation.md whose nearest antecedent was the page sequence rather than the resolver. Lingity architecture-review 1.3.0, measured against the pre-edit bytes: HRI high defects sub-floor file.md 37.08 -> 44.65 6 -> 5 77 -> 63 0 git.md 32.91 -> 39.46 10 -> 6 96 -> 83 0 http-federation.md 18.08 -> 22.04 13 -> 9 160 -> 144 0 mapping.md 8.78 -> 11.45 17 -> 12 215 -> 198 1 -> 0 Every protected_delta reported specified counts matching exactly the attributions the editor authorized, and nothing else. The documents do not meet the HRI 85 floor. The residue is dominated by the mandated RFC 2119 boilerplate, Markdown link targets counted as parentheticals, anchors read as hyphenated compounds, the literal <RESOURCE> placeholder token, and defined domain nouns. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Apply editor-approved Lingity repairs. Every change was an explicit editor decision; no actor or fact was invented. oci.md - Split the long sentences in the three substantive blocks that scored below the policy floor, covering portable entity configs, Version document placeholders and the untrusted-blob security rules. - Made the scope and capture-claim paragraphs active, so the binding and the claim state what they do not define rather than listing excluded nouns. - Gave an actor to obligations whose subject was a thing, using only parties the surrounding text already names: rewrite and duplicate to producers; preserve, validate, decode, reject and resolve to consumers; present to the resolver; forward to the layout reader. federation/spec.md - Split the relative-document-base rule and replaced two nominalizations with verbs. - Attributed obligations after surveying all nineteen actorless MUSTs against their sections: fill, disguise, report, return and scope to the resolver; handle, accept, interpret and treat to the consumer. LING-AGENCY-001 fell from 19 to 6. Lingity architecture-review 1.3.0, measured against the pre-edit bytes: HRI high defects sub-floor oci.md 4.40 -> 5.65 22 -> 18 315 -> 293 3 -> 0 federation/spec.md 10.13 -> 10.30 22 -> 20 266 -> 240 0 Both protected_delta results reported specified counts matching exactly the attributions the editor authorized, and nothing else. Four obligations in oci.md and four in federation/spec.md keep no actor, because the source does not determine one. They remain open rather than resolved. The residue is otherwise dominated by the mandated RFC 2119 boilerplate, Markdown link targets counted as parentheticals, section anchors read as hyphenated compounds, the literal <RESOURCE> placeholder, and defined domain nouns such as federation, selection and advertisement. tools/verify.py succeeds and the full suite passes, 1179 tests. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Apply editor-approved Lingity repairs to the OPC UA binding draft. Every change was an explicit editor decision. Structure: - Split the Scope sentence so the entities and the operations performed on them are stated separately, and the binding states what it realizes in its own sentence. - Turned the OPC UA Service inventory into a list. - Split the resource deletion rule so the Method, its ExpectedEpoch argument and its effect are separate statements. - Rewrote the inverse import paragraph with one verb per sentence. Responsibility, using only parties the surrounding text already names: check, reset, write, ignore and reject to the server; report to the client. Lingity architecture-review 1.3.0, measured against the pre-edit bytes: blocks below the 85 floor 16 -> 9 lowest substantive block 76.10 -> 80.15 high severity 95 -> 82 policy violations 112 -> 92 defects 979 -> 955 The four edited blocks now score 83.07, 100, 100 and 97.36. protected_delta reports specified 4, matching exactly the server and client attributions the editor authorized. The inverse import paragraph needs a note. Its six claims previously carried the actor "inverse import process". They now carry the pronoun "it", whose antecedent is that same phrase in the preceding sentence, and they merge into four claims because coordinated objects combine. An earlier bullet conversion of this paragraph was reverted because it lost the actor entirely; the one-verb-per-sentence form keeps it. About twenty LIST, ACTION, CLAUSE and SENTENCE findings remain structurally fixable, and the nine remaining sub-floor blocks are mostly those. This commit stops at the point of narrowing returns, not at an exhausted document. The rest of the residue is dominated by OPC and UA read as undefined acronyms, section anchors read as hyphenated compounds, the mandated RFC 2119 boilerplate, a 35-item normative type inventory the editor chose to keep, and 100 LING-ACTOR-001 and 131 LING-PASSIVE-001 findings retained by editor decision. tools/verify.py succeeds. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Apply editor-approved Lingity repairs to the two domain model drafts. openusd/spec.md - Split the dependency-closure sentence so the definition, the Consumer consequence and the USD failure mode are separate statements. registry/spec.md - Split the Core terminology sentence, the JSON Pointer rule and its if-and-only-if condition, and the catalog consumer conformance requirements. Lingity architecture-review 1.3.0, measured against the pre-edit bytes: HRI high defects sub-floor openusd/spec.md 4.09 -> 4.09 28 -> 28 416 -> 413 3 -> 2 registry/spec.md 7.85 -> 9.67 17 -> 14 320 -> 318 2 -> 0 Both protected_delta results report specified 0, so no actor was named. The editor was asked again about the usdassetid derivation rule in openusd/spec.md, which an earlier session recorded as open because no actor was determinable. Section 2.2.4 now defines Producer, which would support an attribution, but the editor chose to keep the sentence passive. It remains open rather than resolved, along with the xid selector rule and the metadata acquisition authorization. Residue in both documents is dominated by Markdown link targets counted as parentheticals, section anchors read as hyphenated compounds, the mandated RFC 2119 boilerplate, and defined domain nouns. In registry/spec.md the sentence "This specification does not define replication, synchronization, dependency resolution or storage" is already active; the rule counts the names of the excluded concepts, which is what the sentence exists to list. tools/verify.py succeeds and the full suite passes, 1179 tests. Signed-off-by: Marc Schier <marcschier@hotmail.com>

marcschier · 2026-09-22T16:26:43Z

Added four readability commits covering the nine non-README Markdown files in this PR (22501b6, 5153143, 87e2995, 3195dbe). No non-Markdown file was touched.

Reviewed with the local Lingity runtime under policy architecture-review 1.3.0 (document HRI >= 85, every substantive block >= 85, zero high-severity findings), measured against the pre-edit bytes of each file.

Document	HRI	High	Sub-floor blocks	Lowest block
`bindings/file.md`	37.08 → 44.65	6 → 5	0	87.25
`bindings/git.md`	32.91 → 39.46	10 → 6	0	87.25
`bindings/http-federation.md`	18.08 → 22.04	13 → 9	0	86.92
`bindings/mapping.md`	8.78 → 11.45	17 → 12	1 → 0	80.58 → 86.28
`bindings/oci.md`	4.40 → 5.65	22 → 18	3 → 0	77.68 → 85.09
`federation/spec.md`	10.13 → 10.30	22 → 20	0	86.58 → 87.25
`bindings/opcua.md`	0.15 → 0.16	95 → 82	16 → 9	76.10 → 80.15
`models/openusd/spec.md`	4.09 → 4.09	28 → 28	3 → 2	80.97 → 81.69
`models/registry/spec.md`	7.85 → 9.67	17 → 14	2 → 0	79.01 → 87.04

Totals: high severity 230 → 194, blocks below the floor 25 → 11, defects 2,844 → 2,707.

What changed

Structure. Split or bulleted the long inline enumerations and multi-clause requirement sentences that drove the LIST, ACTION, CLAUSE and SENTENCE findings. Every list introduced follows this repo's capitalized-bullet rule, which tools/verify.py enforces.

Responsibility. Gave an actor to obligations whose grammatical subject was a thing, using only parties the surrounding text already names:

file.md — check/guess → resolver, infer → implementation, read → consumers
git.md — peel/report → resolver
http-federation.md — use → resolver
mapping.md — allocate/copy → producer, reject → consumer
oci.md — forward → layout reader, reject/resolve → consumer
federation/spec.md — fill/disguise/report/return/scope → resolver; accept/treat → consumer
opcua.md — check/reset/write/ignore → server, report → client

Protected meaning

Each document's final comparison used --baseline against its byte-exact pre-edit original, and each artifact was verified to record that original's hash. Across all nine, protected_delta reports 26 specified elements, every one corresponding to an attribution listed above. No actor was named anywhere else.

The missing/added pairs are sentence re-segmentation: the claim extractor keys a claim on a word-bag of its whole sentence, so splitting one sentence retires the long claim and registers the shorter ones.

Deliberately not changed

Twelve obligations keep no actor because the source does not determine one. They remain open rather than resolved: three in models/openusd/spec.md (the usdassetid derivation rule, the xid selector rule, and metadata acquisition authorization), five format constraints in oci.md, and four concept constraints in federation/spec.md.

The residue is dominated by findings that are not defects:

The mandated RFC 2119 boilerplate, which must stay byte-identical.
Markdown link targets counted as prose parentheticals — several report "4 parentheticals, 0 commas".
Section anchors read as hyphenated compounds, such as #worked-example-map-one-existing-file.
OPC, UA, XID, OCI and USD read as undefined acronyms.
The literal placeholder token <RESOURCE>, and the Windows device names CON, PRN, AUX, NUL in backticks.
Defined domain nouns such as dependency closure, capture, federation, selection and advertisement.

opcua.md is the one document that is not finished: roughly 21 structurally fixable findings remain, and its 9 remaining sub-floor blocks are mostly those. Editing stopped there at narrowing returns.

None of these documents meets the HRI 85 floor, and that is a property of applying a plain-language policy to normative specifications rather than a defect list to burn down.

Validation

tools/verify.py . — succeeded after every batch.
Full test suite — 1,179 passed.
git diff --check — clean; LF endings preserved, zero CR bytes.
All four commits signed off.

Removed outdated tools and tests section from README. Signed-off-by: Marc Schier <marcschier@users.noreply.github.com>

The README described only the federation specification family, so the OpenUSD Artifact Registry draft had no entry despite being a peer domain model under workingdrafts/models. Add a section covering what the draft defines, the dependency closure it makes describable, its use of the Core document store so an unmodified USD asset resolver can retrieve artifacts by URL, and its informative cross-references to the Schema and Endpoint registries. Declare usd, MaterialX, plugins and federatable in the README's own words comment, matching how the OpenUSD specification declares them, rather than adding them to the shared dictionary. Two repairs to the preceding commit, which removed the tools and tests section: - Drop the leftover fragment "xamples use `python -m` so imports resolve across bundles." Its opening words went with the removed section, and the section it referred to no longer exists. No replacement section is added, since the removal was deliberate. - Remove a trailing space from the introduction, which made tabcheck exit 1 and would have failed the verify workflow. Also declare reserialize in the directory mapping draft's words comment. An earlier commit in this branch rewrote "MUST NOT be decoded, reserialized" into "Consumers MUST NOT decode, reserialize", and the bare verb form was not in the file's allowlist. This was caught by the failing spellcheck stage on the previous push. Verified with the repository's own gates: spellcheck, tabcheck across every Markdown and JSON file, ticks and badhrefs all pass, tools/verify.py succeeds, and the full suite passes with 1179 tests. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Integrate the OPC UA event binding and the distinct Resource/Version node model from xregistry#568 into the federation binding work on main. xregistry#568 branched from 18eb428, 52 commits back, so both sides had rewritten the same file: xregistry#568 by +835/-352 and main by +753/-273. The merge produced 32 conflicts. Both sides had claimed section 9 for different features. xregistry#568 used it for Events and main used it for Federation. The integrated numbering follows xregistry#568: Events is 9, Federation is 10, Error handling is 11 and Conformance is 12. Main's six federation subsections moved to 10.1 through 10.6 and its resolver-outcome subsection to 11.1. Content kept from xregistry#568: - The whole Events family, 9.1 through 9.7, covering the canonical EventTypes, field mapping, EventSourceUrl, emission rules, notifier topology, subscription and filtering, and delivery lifetime. - The distinct Resource and Version model: a logical Resource owning a typed ResourceVersionsType component named Versions, with exact Version Objects below it, and Resource Meta carried by MetaEpoch, MetaLabels, MetaCreatedAt and MetaModifiedAt. - The pinned companion model, Version 0.6.0 at commit d3399fca with its NodeSet digest. - The export-capable, event-capable and client conformance clauses, including the XREG-Events conformance unit. - The federated proxy rule, which local proxy Objects must obey. Content kept from main, none of which xregistry#568 had seen: - Section 1.1 Motivation, 8.1 Native metadata and navigation and 8.2 Core document-view export. - The full federation section. xregistry#568 carried a 36-line version; main's is 206 lines with advertisement and Registry selection, structured reference resolution, the three distinct reference mechanisms, trust and live consistency, namespace export and the pinned companion gaps. - Section 11.1 Federation resolver outcomes and its outcome table. - The readability work from the Lingity sessions, including the bulleted operation model and the named obligation holders. Where the two sides described the same rule differently, the merged text keeps main's sentence structure and xregistry#568's model vocabulary. The scope paragraph, the resource deletion rule and the serialization section are resolved that way. Verified that nothing was dropped. Every xregistry#568 marker survives at its original count: ResourceVersionsType 8, MetaEpoch 46, MetaCreatedAt 12, AssignedVersionId 9, EventSourceUrl 7, incarnation 7. Every main marker survives as well. Obligation counts rise to MUST 190, SHOULD 13 and MAY 35, against 138/8/27 on main and 137/12/36 on xregistry#568, consistent with a union of two feature sets rather than a replacement of one by the other. Five Events cross-references had to be restored to section 9 after the federation renumbering moved them, and four rules from xregistry#568 that the conflict resolution had truncated were added back: the MetaLabels reads and label Methods in the operation model, the MetaLabels coverage in recursive delete, and the federated proxy rule. tools/verify.py succeeds, spellcheck, tabcheck and badhrefs pass, and the full suite passes with 1179 tests. Signed-off-by: Marc Schier <marcschier@hotmail.com>

Adopt the seven merged upstream changes to Core, Endpoint item enums, generated artifacts, the fail-fast model validator and site dispatch. Preserve all workingdrafts content including merged PR568 native Events and distinct Resource/Version nodes. Keep the mainline generator unchanged and the authored PR scope confined to workingdrafts plus existing supporting-tool exceptions. Signed-off-by: Marc Schier <marcschier@hotmail.com>

marcschier and others added 8 commits September 3, 2026 07:22

docs(opcua): separate resource and version nodes

32462c2

Signed-off-by: Marc Schier <marcschier@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5

docs(opcua): pin companion model revision

e9ea81b

Signed-off-by: Marc Schier <marcschier@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5

docs(registry): revise catalog terminology for 1.0-rc1

baaf1a2

Record local Registry draft edits, including updated model versions and removal of the hub-compatibility and source-crosswalk sections. Signed-off-by: Marc Schier <marcschier@hotmail.com>

marcschier commented Sep 10, 2026

View reviewed changes

Comment thread core/primer.md Outdated

Comment thread cloudevents/schemas/document-schema.avsc

marcschier added 2 commits September 10, 2026 20:18

marcschier commented Sep 11, 2026

View reviewed changes

Comment thread schema/schemas/document-schema.avsc

marcschier commented Sep 11, 2026

View reviewed changes

Comment thread workingdrafts/bindings/mapping.md

Comment thread workingdrafts/bindings/document-format.md Outdated

Comment thread workingdrafts/bindings/mapping.md

marcschier commented Sep 11, 2026

View reviewed changes

Comment thread workingdrafts/bindings/oci.md

Comment thread workingdrafts/bindings/git.md Outdated

marcschier commented Sep 11, 2026

View reviewed changes

Define producer and consumer federation resolution signaling

e032512

Signed-off-by: Marc Schier <marcschier@hotmail.com>

marcschier force-pushed the main branch from d5ae46b to e032512 Compare September 11, 2026 12:40

marcschier and others added 2 commits September 11, 2026 15:39

Merge branch 'xregistry:main' into main

151c578

marcschier mentioned this pull request Sep 15, 2026

Spec items that could use fixes/corrections from clean room implementation effort #721

Open

18 tasks

marcschier changed the title ~~DRAFT: Add registry federation specifications and transport bindings~~ Add registry federation specifications and transport bindings working drafts Sep 18, 2026

marcschier added 10 commits September 21, 2026 12:46

marcschier mentioned this pull request Sep 22, 2026

docs(openusd): restructure run-on requirement prose marcschier/xregistry-drafts#3

Closed

marcschier added 2 commits September 22, 2026 10:32

marcschier marked this pull request as ready for review September 22, 2026 10:28

marcschier added 4 commits September 22, 2026 15:54

marcschier and others added 2 commits September 22, 2026 18:48

Update README to remove tools and tests section

6bce123

Removed outdated tools and tests section from README. Signed-off-by: Marc Schier <marcschier@users.noreply.github.com>

marcschier force-pushed the main branch from 8a3366a to f3155ae Compare September 22, 2026 16:48

marcschier mentioned this pull request Sep 23, 2026

Add native events and distinct Resource versions to OPC UA binding working draft #568

Closed

marcschier changed the title ~~Add registry federation specifications and transport bindings working drafts~~ Add federation and transport bindings working drafts Sep 23, 2026

Conversation

marcschier commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Current-main refresh

Proposed Changes

Specifications

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marcschier Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marcschier commented Sep 22, 2026

Uh oh!

marcschier commented Sep 22, 2026

What changed

Protected meaning

Deliberately not changed

Validation

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

marcschier commented Sep 10, 2026 •

edited

Loading