Skip to content

Source identifiers rev2: identifier packages are heterogeneously typed across all four verticals - #7

Open
asluk wants to merge 38 commits into
aluk/source-identifiers-comparisonfrom
aluk/source-identifiers-rev2
Open

Source identifiers rev2: identifier packages are heterogeneously typed across all four verticals#7
asluk wants to merge 38 commits into
aluk/source-identifiers-comparisonfrom
aluk/source-identifiers-rev2

Conversation

@asluk

@asluk asluk commented May 6, 2026

Copy link
Copy Markdown
Owner

Summary

This PR carries the source-identifier comparison work on aluk/source-identifiers-rev2. The canonical read is extras/sourceIdentifiers/COMPARISON.md; this description orients reviewers to what the PR contains.

The proposal context: PixarAnimationStudios/OpenUSD-proposals#105 (Separation of Concerns for Identifiers) frames source identifiers as "metadata packages, not atomic strings" with "different identifier fields" per domain — a heterogeneity it asks AOUSD to weigh.

What's in this PR

  • Pre-registered field census (extras/sourceIdentifiers/details/field_classification_experiment.md) — fields drawn from authoritative spec surfaces (IFC4x3, Revit API, AAS metamodel, Windchill REST, SAP MARA, ROS / URDF / SDF, OpenAssetIO / MovieLabs OMC / ShotGrid) under classification criteria committed before any field was enumerated. Headline finding: identifier packages are heterogeneously typed in every vertical surveyed — timestamps universal; numeric measures with units in three of four; composite typed references universal; polymorphic XSD-typed values systematic in AAS.

  • Four candidate mechanisms compared symmetrically — A (assetInfo dictionaries), B (multi-apply schema with four typed common fields), C (B + assetInfo overflow), D (A's mechanism + UsdSemanticsLabelsAPI for classification facets). The comparison reads symmetrically across A/B/C/D; no leaning is asserted. Structurally, D = A's mechanism + Labels-for-classification — A and D share the same assetInfo overflow tier, and the A-vs-D differentiator is whether classification facets ride UsdSemanticsLabelsAPI or live in assetInfo like everything else.

  • Principle-derived scoring (extras/sourceIdentifiers/stress_tests/vendor_adoption_analysis.{py,json}) re-derived 2026-05-07 from primitives. Each per-dimension question rubric is anchored to its principle's literal text without broadening; each per-mechanism score is derived from primitive-level inspection of that candidate's actual mechanism (schema definitions, example files, AOUSD Core Spec primitives, the field census). Totals (max 40): A=36, B=34, C=37, D=38. The four candidates cluster within a 4-point spread.

    Four of the eight principles produce check-pass scores across all four candidates at the literal-text reading (Separation of concerns, Composability, Round-trip fidelity, Minimal disruption). The differentiating dimensions are Industry agnosticism (B trails because its fixed four-property surface admits only a common subset; A/C/D admit the full identifier-package shape via dict tiers), Vendor extensibility (A/D ship today via assetInfo overflow + spec-text-formalization promotion; C ships via overflow as fallback with the typed tier requiring schema ratification; B blocked on data-model approval), Discoverability (B/C/D surface per-system from apiSchemas; A is parse-based on the standardized sourceIds key), and External queryability (B is fully schema-targeted; C/D mixed; A parse-based).

  • Implementation-level considerations are surfaced separately (per PR 105 Add Python fixer support for usdValidation #3, vendor extensions are at the data-model level and distinct from OpenUSD plugins as a runtime implementation detail): schema-ratification cost (B and C), schema-distribution cost (B and C, conditional per Aaron's 2026-05-07 call — currently elevated as the AOUSD Build IG epic aousd/build-ig-initiatives#28 scopes the substrate, trending lighter as those initiatives land), spec-text-formalization track record (A and D), and per-vertical conditionality of D's classification advantage. These do not feed the principle-derived totals; they are real for the AOUSD ratification decision and read separately.

What changed in this revision

The principle-derived scoring was re-derived from primitives in a full rerun (2026-05-07), not patched. The earlier scoring iteration (preserved as vendor_adoption_analysis_legacy.py) carried interpretive broadenings of several principle texts — notably Minimal disruption, broadened to include schema ratification and plugin distribution — which conflated standard-level disruption (the principle text's literal scope) with implementation-level rollout cost and double-counted with Vendor extensibility (which already captures schema-ratification cost as a barrier to ship-today). The current scoring narrows to literal text and surfaces implementation-level concerns separately. Effects: the spread tightens from the prior 26–36 (10 points) to 34–38 (4 points); A picks up on Separation of concerns (literal text is USD-path vs external-ID, not within-package separation); B picks up on Minimal disruption and on Industry agnosticism (carries the primary identifier from any industry's scheme cleanly even if it doesn't carry the heterogeneous typed surface beyond the common subset); D drops one point on Discoverability (per-(system, facet) granularity is a meaningful capability surfaced in the rationale and in the per-vertical conditionality note, but not the principle text). C and D each pick up two-to-three points on the literal-text reading.

Methodology retrospective

Methodology lessons from this work — pre-registered classification before field enumeration, principle-derived scoring narrowed to literal text, primitive-level verification of mechanism architecture, treating "rerun" as full re-derivation rather than patch-on-patch — are captured in a PR comment. Talk-prep material rather than gating reading.

Test plan

  • examples/verify_column_d.py — verifies column_d.usda parses against built USD with UsdSemantics.LabelsAPI (0 failures)
  • stress_tests/generate_approach_{a,b,c,d}.py — 100K-prim deterministic generators; reproducible
  • stress_tests/vendor_adoption_analysis.py — principle-derived scoring reproducible across A/B/C/D; rubrics published in DIMENSIONS; per-mechanism rationales and implementation considerations in JSON output
  • details/field_classification_experiment.md — pre-registered classification criteria committed before field enumeration; cross-vertical bucket totals reproducible from the cited spec sections

asluk and others added 2 commits May 6, 2026 13:44
Approach D (Labels + Identity) decomposes the source-identifiers problem
along its natural seams: opaque identifier strings live in
assetInfo["source"][<system>]; classification facets ride per-facet
SemanticsLabelsAPI:<system>:<facet> instances. No new applied schema —
UsdSemanticsLabelsAPI is in OpenUSD core (24.11+).

Scenarios mirroring the existing A/B/C scenario set:
- examples/column_d.usda — AECO column (canonical example)
- examples/manufacturing_d.usda — tractor assembly (Windchill, Mercedes,
  feature IDs); identity-vs-classification split test surfaced borderline
  fields (displayNumber, state, lifecyclePhase) flagged for TAC validation
- examples/robotics_d.usda — warehouse fleet (ROS, fleet, manufacturer)
- vendor_simulation/approach_d_vendors.usda — 8-vendor ecosystem
  (NVIDIA / Adobe / Apple / SideFX / Autodesk / IFC / ASHRAE / STEP)

Empirical machinery:
- stress_tests/generate_approach_d.py — deterministic 100K-prim generator
  (random.seed(42)). Real measurements: D=115.82 MB / 3.09M lines /
  11 apiSchema instances + 11 label props + 9 dict keys. Sits between
  A (109.38 MB) and C (147.06 MB), larger than B (93.09 MB) by the
  per-facet apiSchema overhead.
- stress_tests/vendor_adoption_analysis.py — re-scored across A/B/C/D
  against eight dimensions (initial adoption, distribution friction,
  per-prim/per-facet discoverability, metadata heterogeneity, validator
  implementability, composition for non-timevarying strings, file size).
  Totals: A=29, B=27, C=29, D=36. Treats collision detection, governance
  enforceability, and composition for non-timevarying strings as
  symmetric across mechanisms.
- stress_tests/{stress_test_results,vendor_adoption_analysis}.json —
  measurement output, regenerable from the scripts.

Verification:
- examples/verify_column_d.py — schema-aware verifier that opens
  column_d.usda against a built USD, applies UsdSemantics.LabelsAPI for
  each (system, facet) instance, reads back the token[] value, and
  validates assetInfo["source"][<system>]. Run against the local USD
  build: 10 SemanticsLabelsAPI instances + 4 assetInfo source dicts,
  0 failures.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Recommends Approach D (Labels + Identity) over the previously documented
hybrid (Approach C). Approach D uses UsdSemanticsLabelsAPI (already
shipping in 24.11) for classification facets plus assetInfo for the
opaque identifier and version, requiring no new applied schema.

COMPARISON.md (807 -> 520 lines):
- Adds Aaron Luk and Matt Kuruc as joint authors
- Replaces three-approach framing (A/B/C) with four (A/B/C/D); D is the
  recommendation, with a "Why D Over C" section explaining the case
- Methodology section surfaces the empirical-first approach as the
  load-bearing contribution; lists the experiments with pointers to
  reproducible artifacts
- §3.1-3.5 findings tables extend to D with measured numbers
- §3.6 vendor adoption scoring (A=29, B=27, C=29, D=36); collision
  detection, governance enforceability, and composition for
  non-timevarying strings treated as symmetric across mechanisms

Deep-dive updates:
- approach_descriptions.md: adds Approach D as a top-level section with
  runnable example; brief C section pointing at hybrid_analysis.md
- composition_behavior.md: leads with "equivalent for non-timevarying
  strings"; round-trip-rewrite hazard noted as a tool-author bug rather
  than a structural property of any one approach
- governance.md: governance treated as symmetric across the four
  mechanisms; D validator pseudocode added; new §6.8 on D collapsing
  most of the schema-distribution discussion in §6.5-6.7
- industry_scenarios.md: D fit per vertical (AECO/manufacturing/
  robotics/M&E); identity-vs-classification split test described per
  vertical; cross-industry table extends to D with "no new schema
  required" column for A and D
- stress_tests.md: real measurements per approach replacing prior
  estimates; A/B/C/D scoring against the §5.3 dimensions; §5.4 reframed
  as a sensitivity check on the C three-tier adoption profile
- hybrid_analysis.md: header reframes C as the fallback design if a
  domain surfaces classification fields needing typed non-token-array
  structure; §7.7 rewritten as the adoption shape if C is used
- scope_promotion_simulation.md: header note that under D the
  multi-stage scope promotion path collapses to a registry-level facet
  addition; original simulation preserved as illustrative of the harder
  C-tier graduation

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@asluk
asluk force-pushed the aluk/source-identifiers-rev2 branch from 470faeb to 2afaca0 Compare May 6, 2026 21:29
Three changes that prepare the comparison work for AOUSD review and the
eventual follow-up proposal:

1. Soften the doc body from "recommend Approach D" to "the data leans
   toward D" — matches the Siemens TL;DR posture for in-progress
   standards work, and reframes C and D as refinements of B (closing
   B's heterogeneity gap two different ways) rather than wholesale
   alternatives.

2. Add details/formality_and_distribution.md, a deep dive that names
   the eight formality benefits a schema delivers (type validation,
   fallbacks, GUI integration, discoverability, typed accessors,
   versioning hooks, validator targeting, schema-driven property
   metadata), breaks down which six are met by reuse of an existing
   core schema (UsdSemanticsLabelsAPI in 24.11+) vs. the two that
   require a new schema (domain-calibrated fallbacks, domain-specific
   schema versioning), and credits the recurring ecosystem-distribution
   cost as the dominant cost of ratifying a new applied schema. The
   AOUSD Build Interest Group coordinates the substrate that
   distribution depends on; see github.com/aousd/build-ig-initiatives#28
   for the parent epic on hosted OpenUSD binaries.

   Across the four verticals tested (AECO / Manufacturing / Robotics /
   M&E), no field surfaced that required the new-schema-only benefits.
   The leaning is empirical, not argued; AOUSD review may surface
   domains where the answer differs.

   COMPARISON.md §1 gets a callout naming the tradeoff and pointing to
   the deep dive; governance.md §6.7 credits ecosystem distribution as
   the dominant cost (above the codegen step it had been emphasizing).

3. Scrub overused phrases from the prose for plainer alternatives. No
   semantic change.
@asluk asluk changed the title Source identifiers rev2: recommend Approach D (Labels + Identity) Source identifiers rev2: comparison leaning toward Approach D (Labels + Identity) May 7, 2026
…carries

The §1 D bullet jumped to schema mechanics without naming what "Labels +
Identity" actually means in the proposal's context. Rewrites it to lead
with the two concerns the mechanism separates — identity (the opaque
round-trip pointer) vs. classification (the controlled-vocabulary terms
each system publishes) — with concrete examples per concern. The
"Where the data leans" paragraph follows the same shape so the seam is
explicit, not implicit.

No semantic change; clarity only.
@asluk asluk changed the title Source identifiers rev2: comparison leaning toward Approach D (Labels + Identity) Source identifiers rev2: leaning toward Labels + Identity May 7, 2026
asluk and others added 6 commits May 6, 2026 19:09
The experiment will test the load-bearing assertion in
formality_and_distribution.md that "no domain-specific field surfaced
needing typed non-token-array structure" across the four verticals.

The four buckets and anti-bias rules are committed up front, before
any field is enumerated. Field sources will be authoritative spec
docs, not the existing industry_scenarios.md (which was constructed
in service of the leaning).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Pulls IFC fields from buildingSMART IFC4x3 lexical reference (IfcRoot,
IfcElement, IfcObject, IfcColumn, IfcOwnerHistory) and Revit fields
from Autodesk's 2024 Revit API documentation.

Surfaces non-token-array typed structure already in the AECO surface:
IFC timestamps (IfcTimeStamp, numeric), IFC composite references
(IfcPersonAndOrganization, IfcApplication), and Revit ElementId-typed
relationships. The claim that token-array+identifier-string carried
every metadata case is not yet refuted across the experiment, but it
already needs qualification: it holds for the canonical classification
work, not for OwnerHistory-style audit metadata.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Pulls fields from IDTA-01001 AAS metamodel (v3.1.1/v3.2), PTC
Windchill REST Services 1.5, and SAP ABAP Data Dictionary for the
MARA Material Master table.

Decisive finding: the AAS metamodel — the explicit Industry 4.0
standard the source-identifier proposal already cites — defines its
identifier-bundled metadata to be polymorphically typed via XSD
(xs:int, xs:decimal, xs:dateTime, xs:boolean, xs:base64Binary) plus
composite References. SAP MARA carries DATS (date) and QUAN(n,m)
(decimal with unit). Windchill exposes Edm.DateTimeOffset.

The previous "7 of 8 simulated PLM/ERP fields fit cleanly" claim was
made against a synthesized 8-field set, not the spec surface. The
load-bearing assertion that no field surfaced needing typed
non-token-array structure does not hold against the Manufacturing/PLM
authoritative specs.

This is an empirical finding only; whether and how to update the
doc's leaning is a downstream judgment that is out of this
experiment's scope.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Robotics census distinguishes strict (package URI surface) from
expanded (round-trip-back-to-URDF) interpretations. Strict is mostly
string/token-friendly except for std_msgs/Header.stamp (numeric pair)
and seq (uint32). Expanded URDF surface is dominantly numeric (mass,
inertia, joint limits, dynamics, geometry params) per urdfdom_headers
and urdfdom parser source.

M&E census surfaces datetime fields (created_at/updated_at) and typed
entity-reference relationships (project, parents, created_by) in
ShotGrid; OMC adds typed version int and structured creationContext /
lifecycleEvents; OpenAssetIO trait property values are typed
polymorphically.

Cross-vertical synthesis: non-token-array typed structure surfaces in
every vertical surveyed, predominantly as timestamps, numeric measures
with units, and composite typed references. Manufacturing/PLM is
heaviest because AAS makes XSD-typed Property values the standard
extension surface.

The load-bearing assertion does not hold as written. Suggests a
narrower defensible form: "for the controlled-vocabulary
classification axis, token-array shape was sufficient" — which
preserves the observation without asserting an absence the specs
refute.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replaces the broader "no field surfaced needing typed non-token-array
structure" assertion with the narrower defensible form the field
census supports: token arrays carry the controlled-vocabulary
classification axis cleanly across all four verticals; non-token-array
typed shapes are scope decisions, not absent requirements.

Adds the field_classification_experiment.md reference to the doc
list, a per-vertical bucket table to Empirical measurements, and a
caveat that the eight-dimension vendor adoption scoring was
constructed after the leaning toward D took shape (rebuild deferred).

Open questions adds where the identifier-package boundary sits as
the load-bearing scope question the leaning now depends on.

PR body pushed to GitHub via gh pr edit.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replace "non-token-array typed structure" with "heterogeneous typed
fields" throughout — proposal PixarAnimationStudios#105's own vocabulary for the same
question. Bucket names follow:

- Identifier strings (was "Identity")
- Identifier-adjacent strings (was "Identity-adjacent")
- Controlled-vocabulary classification facets (was "Classification —
  token-array fit")
- Heterogeneous typed fields (was "Classification — non-token-array
  typed structure")

Replaces "Effect on the load-bearing assertion" with "What the census
shows / What this means for the comparison's previous claim / What
this means for mechanism choice." Drops the rescued narrower-form
framing that preserved D's leaning post-hoc. Honest finding:

- Identifier packages are heterogeneously typed across all four
  verticals surveyed
- The proposal's own heterogeneity tension is real, not empty
- A and C carry typed heterogeneity; D and B-alone do not
- D's leaning depended on a scope-narrowing the data does not show
  to be appropriate
- The leaning toward D is not earned by this empirical work

Quoted text from the original assertion (in formality_and_distribution.md)
is left verbatim so the historical claim is citable.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@asluk asluk changed the title Source identifiers rev2: leaning toward Labels + Identity Source identifiers rev2: identifier packages are heterogeneously typed across all four verticals May 7, 2026
asluk and others added 12 commits May 6, 2026 19:39
Title: "Source identifiers rev2: identifier packages are
heterogeneously typed across all four verticals" — reflects what
the fresh empirical data shows, not a verdict among A/B/C/D.

Body changes:
- Drops "the data leans toward D" framing entirely
- Replaces with the empirical finding: identifier packages are
  heterogeneously typed (timestamps universal; numeric measures with
  units in 3 of 4 verticals; composite typed references universal;
  polymorphic XSD typing the standard surface in AAS)
- Maps the four candidates onto the heterogeneity finding: A and C
  carry typed heterogeneity; D and B-alone do not as complete answers
- Notes D was constructed downstream of the proposal's authorized
  A/B/C, included as an explored idea, not a peer candidate
- Drops the Siemens-prep "feed back into PixarAnimationStudios#105 as use-case refinement,
  not back-edit it" phrasing — that belongs to a different workstream
- Eight-dimension scoring caveat preserved; framing-deconstruction
  list expanded to cover all the docs the rebuild plan named
- Open questions explicitly include the where-does-the-boundary-sit
  scope question as load-bearing for AOUSD review

PR title and body pushed via gh pr edit.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Removes "Where the data leans" leaning-toward-D section and replaces
with the empirical finding from the field experiment: identifier
packages are heterogeneously typed across all four verticals.

Reframes §3.4 industry scenarios to report findings symmetrically
across A/B/C/D rather than narrating "Approach D fit" per vertical.

Reframes §3.6 vendor adoption scoring with explicit retraction of
the synthesizing-verdict framing; preserves scores as illustrative
of per-mechanism contrasts, not as an independent verdict; flags two
specific dimensions (D's heterogeneity score; distribution friction
weighting) as known issues against the field experiment.

Removes the "Where the data leans toward D's refinement over C's"
section entirely.

Open questions reordered to put the identifier-package scope question
first (load-bearing for any mechanism choice).

Drops the Siemens-prep "feed back into PixarAnimationStudios#105 as use-case refinement,
not back-edit it" sentence from Status section.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…ension

Retracts the assertion that "no domain-specific field surfaced
needing typed non-token-array structure" with explicit reference to
the field experiment that shows otherwise. Reframes the
formality/distribution tradeoff as three-dimensional: formality
benefits, distribution cost, AND whether the mechanism carries the
heterogeneous typed surface real source systems bundle.

Updates the per-mechanism tradeoff table to add the heterogeneity
column. A and C carry it; B-alone and D do not.

Open questions are reordered to put the identifier-package boundary
question first as load-bearing for any mechanism choice.
Distribution-friction tension is named explicitly with both sides
(D's elevation vs. proposal's original B-cons phrasing).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Adds note at top distinguishing the synthesized field set this
document is built on from the authoritative spec-surface census in
field_classification_experiment.md. The synthesized set covers the
controlled-vocabulary classification axis cleanly; the spec surfaces
include heterogeneous typed fields the synthesized set does not
represent.

Per-vertical "Approach D fit" sections retitled "(synthesized field
set only)" and supplemented with explicit notes on the wider
identifier surface D does not cover (IFC OwnerHistory, AAS Property
typed values, SAP DATS/QUAN, URDF numeric content, ShotGrid datetimes
and entity refs).

§4.5's "three-tier C model is a fallback if a future domain surfaces
typed structure" framing retracted: every vertical surveyed surfaces
such fields, so C's three-tier model is a present-day fit, not a
fallback.

Cross-industry synthesis: separate paragraphs for "what the
synthesized set shows" vs. "what reading against the spec surfaces
shows." A and C accommodate the wider surface; B-alone and D do not.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
hybrid_analysis.md: retracts "C is the natural fallback if D doesn't
fit" framing. The field experiment shows heterogeneous typed fields
surface in every vertical surveyed, so C is a present-day fit, not
a fallback for hypothetical future domains.

approach_descriptions.md: D's section now carries an explicit
provenance note (constructed downstream of proposal PixarAnimationStudios#105, included
as an explored idea, not a peer candidate the proposal authorized).
C's "natural fallback" framing removed; described on its own merits.

stress_tests.md §5.3: retracts "scoring leans toward D" finding. Two
specific issues flagged: D's metadata-heterogeneity score of 4
cannot be reconciled with the spec-surface heterogeneity the field
experiment documents; the distribution-friction weighting is itself
a load-bearing open question. A re-derivation of dimensions from
the proposal's eight authorized principles is part of the rebuild
plan and is deferred.

scope_promotion_simulation.md: scope-of-this-simulation note
reframed. The earlier "D collapses this to a registry-level facet
addition; C's path is preserved as illustrative of harder graduation"
wording asymmetrically privileged D; replaced with a balanced note
that distinguishes controlled-vocabulary fields (which can ride D's
labels) from heterogeneously typed fields (which need C's path),
with the field-experiment finding that real domains surface both.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…eriment

Two deferred items are now called out up front so any agent reading
the materials lands on them:

1. The eight-dimension vendor-adoption scoring in
   stress_tests/vendor_adoption_analysis.{py,json} was constructed
   after a prior leaning toward D had taken shape; not re-derived
   from the proposal's eight authorized principles.
2. The distribution-friction tension between formality_and_distribution.md
   (elevates distribution to dominant cost) and proposal PixarAnimationStudios#105's
   original B-cons phrasing (downplays it) is unresolved. Aaron's
   call needed.

Each caveat block also notes that a prior leaning toward D has been
retracted in light of the field census, and points to the rebuild plan
memory note tracking the deferrals.

Caveat block added at top of:
- _pr7_body.md (pushed to GitHub via gh pr edit)
- extras/sourceIdentifiers/COMPARISON.md
- extras/sourceIdentifiers/details/field_classification_experiment.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…rong repo

GitHub markdown auto-links bare #N references to the current repo,
so on the asluk/USD PR page "proposal PixarAnimationStudios#105" was resolving to
asluk/USD#105 (does not exist) rather than to OpenUSD-proposals
where the proposal actually lives.

Replaces "proposal PixarAnimationStudios#105" with "proposal 105" in prose contexts and
"Proposal PixarAnimationStudios#105's" with an explicit linked form in the PR body
caveat. Fully-qualified [PixarAnimationStudios/OpenUSD-proposals#105]
link forms throughout the docs are unchanged because they already
resolve correctly via the explicit URL.

Affects:
- _pr7_body.md (pushed via gh pr edit)
- extras/sourceIdentifiers/COMPARISON.md
- extras/sourceIdentifiers/details/field_classification_experiment.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The "Memory note for agent readers: ...project_source_identifier_rebuild.md"
line in the PR body leaked an internal memory file path to public
readers. Removed.

Replaces it with an explicit "Share-readiness" line in all three
caveat blocks (PR body, COMPARISON.md, field_classification_experiment.md):
this PR is not ready to recirculate broadly (additional NVIDIA
reviewers, Matt, or AOUSD members) until the two deferred items
(scoring re-derivation, distribution-friction call) resolve. The
empirical census stands on its own; the comparison framing around
it does not.

Also fixes a doubled-word typo ("proposal proposal's") in
COMPARISON.md introduced by the earlier PixarAnimationStudios#105 cleanup.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replaces the eight ad-hoc dimensions (constructed after a leaning
toward Approach D had already taken shape) with eight dimensions
derived from proposal 105's eight authorized design principles
(separation of concerns, industry agnosticism, vendor extensibility,
composability, discoverability, external queryability, round-trip
fidelity, minimal disruption).

Each dimension carries a published 1-5 anchor and a per-mechanism
justification. The numerical totals are illustrative; the anchors
and justifications are the primary reading.

Aaron's 2026-05-07 call on schema-distribution friction (conditional
- currently heavy, trending lighter as the AOUSD Build IG epic
resolves) is reflected in the Minimal disruption score for B and C
and called out in the methodology.

Rebuilt scoring totals (max 40):
  A=32  B=26  C=32  D=33

A, C, and D are within scoring noise (3-point spread); B trails
meaningfully. The principles do not pick a single winner among
A/C/D - each has different strengths, and the choice between them
depends on which principles the AOUSD review weights most heavily.

Legacy script preserved as vendor_adoption_analysis_legacy.py so the
prior scoring is citable and the regression to it can be inspected.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replaces the retracted ad-hoc scoring with the principle-derived
rebuild. Each section now reports the eight dimensions derived from
proposal 105's authorized principles, with totals A=32 / B=26 /
C=32 / D=33 — A/C/D within 3-point scoring noise, B trailing
meaningfully.

Both sections include the conditional-weighting note on Minimal
disruption per Aaron's 2026-05-07 distribution-friction call:
currently elevated as the AOUSD Build IG epic scopes the substrate,
trending lighter as those initiatives land.

The "How to read these" / "Where each approach lands" narratives
report symmetrically across A/C/D, calling out where each leads and
where each pays. No leaning asserted.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…-05-07 call

The unconditional "dominant cost" framing is retracted. Replaced
with the conditional reading: matrix burden is currently elevated
because fragmented across vendors who ship USD binaries today;
trending lighter as the AOUSD Build IG epic resolves (hosted
binaries, plugin registration via importlib, conda-forge / PyPI
distribution).

Frames the difference from proposal 105's B-cons as one of
articulation, not of correctness — the proposal flagged the burden;
this doc elaborates what it looks like operationally as a build
matrix.

The rebuilt scoring in vendor_adoption_analysis.{py,json} reflects
the conditional weight directly in the Minimal disruption score for
B and C.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Caveat blocks across all three docs updated to reflect that both
deferred items landed in the 2026-05-07 rebuild:

- Scoring re-derived from proposal 105's eight authorized principles
  (legacy script preserved as vendor_adoption_analysis_legacy.py)
- Distribution-friction tension resolved as conditional (currently
  elevated, trending lighter as the AOUSD Build IG epic lands)

Caveat blocks now read as "Reader's note" rather than
deferred-items lists. Share-readiness flips from "not yet ready"
to "ready for renewed review and recirculation."

PR body: vendor-adoption-scoring section replaced with the rebuilt
principle-derived table (A=32, B=26, C=32, D=33). Doc-reframing list
updated. Existing-artifacts table notes the legacy script. Test plan
updated.

PR body pushed via gh pr edit.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@asluk

asluk commented May 7, 2026

Copy link
Copy Markdown
Owner Author

Methodology retrospective — how this PR landed

Posted as a comment so the body reads as the current state of the work. Capturing the journey here for future talks on the empirical-first approach to standards work.

The journey (2026-05-06 → 2026-05-07)

The PR began with a leaning toward Approach D (Labels + Identity using the existing UsdSemanticsLabelsAPI + assetInfo). The leaning was constructed downstream of proposal 105 — an unauthorized expansion of a strawman question into a peer candidate. Around it, eight scoring dimensions Claude had invented across the comparison work were augmented with D and used to validate the leaning. Those dimensions never derived from the proposal's eight authorized principles; they were ad-hoc from the start (the original April-2026 A/B/C version on the aluk/source-identifiers-comparison base branch was already that way), and the D-augmented rev2 version inherited the pattern and biased toward D along axes D happens to lead on by construction (per-facet discoverability; "no new schema = higher" distribution-friction framing). The D-augmented snapshot is preserved at stress_tests/vendor_adoption_analysis_legacy.py; the earlier A/B/C snapshot is reachable via git history.

Scope of the rebuild. The principle-derived scoring rebuild reaches back through the entire ad-hoc lineage, not just the D sub-period. Changes apply to rev2's HEAD (this PR); the base branch aluk/source-identifiers-comparison picks up the rebuild on merge. Until then, anyone looking at the base branch directly sees the pre-rebuild ad-hoc state.

The rebuild executed two passes plus a re-derivation:

1. Empirical-first re-anchoring. A pre-registered field census against authoritative spec surfaces — IFC4x3, Revit API, AAS metamodel, Windchill REST, SAP MARA, ROS / URDF / SDF, OpenAssetIO / MovieLabs OMC / ShotGrid — showed identifier packages are heterogeneously typed across all four verticals surveyed. Timestamps universal; numeric measures with units in three of four; composite typed references universal; polymorphic XSD-typed values systematic in AAS. Not the empty heterogeneity surface the prior "no field surfaced needing typed structure" framing required. The leaning was retracted; the comparison reads symmetrically across A / B / C / D.

2. First principle-derived scoring. The eight invented dimensions were replaced with eight derived from proposal 105's eight authorized design principles — separation of concerns, industry agnosticism, vendor extensibility, composability, discoverability, external queryability, round-trip fidelity, minimal disruption. Per-mechanism justifications were grounded in primitive-level verification of each candidate's mechanism architecture: D's assetInfo["source"][<system>] is a full overflow tier accepting the broad USD VtDictionary value-type set the same way Approach A's assetInfo["sourceIds"] does — D = A's mechanism + UsdSemanticsLabelsAPI for classification facets, structurally. (Earlier drafts of the comparison materials had characterized D as "labels + identifier strings only," collapsing it onto its classification tier; the rebuild corrected that reading.) Schema-distribution friction tension resolved as conditional (currently elevated, trending lighter as the AOUSD Build IG epic aousd/build-ig-initiatives#28 lands). At this point, the principle-derived scoring still carried two unaddressed problems that surfaced later: interpretive broadenings of principle texts (notably Minimal disruption, broadened to include schema ratification and plugin distribution beyond the literal text's "composition engine or namespace path semantics") and per-mechanism rationales for A/B/C that hadn't been independently re-derived from primitives — they had been adapted from the prior ad-hoc justifications.

3. Patch attempts that misinterpreted "rerun" as patch-on-patch. A synthesis review subsequently surfaced the D-architecture correction (D = A + Labels-for-classification, not labels-only) and named several specific overclaims and rubric broadenings carrying through the materials. Aaron instructed a rerun. The instruction was interpreted as patch-on-patch rather than as full re-derivation: explicit wrong claims surfaced by the synthesis got patched, but dimensions, rubrics, and per-mechanism scores were not re-derived from primitives. The patch sequence — b60582421 (soften "AAS most strongly typed" overclaim), 95a6fd8f2 (fix "3-point spread" arithmetic to actual 1; fix "the standard surface in AAS" overclaim), f56a111d7 (commit message reads "Apply corrected D-architecture reading; rerun principle-derived scoring" but applied D-architecture corrections as targeted edits to existing per-mechanism rationales rather than re-deriving), plus in-flight pattern-match edits to §3.2 Discoverability and §3.3 Governance tables that 98396221b checkpoints — each addressed a specific wrong cell or claim. None re-derived from primitives. The implicit shape errors (table cells and per-mechanism descriptions structured around the wrong framing without containing any explicitly false statement) and the inherited interpretive broadenings (the Minimal disruption broadening was untouched through the patch sequence; A/B/C per-mechanism rationales remained adapted-from-prior rather than primitive-derived) survived. The patches made the artifacts incrementally less wrong without correcting their structural foundation.

4. Re-derivation rerun (2026-05-07, this session). A fresh-agent re-derivation. Each per-dimension question rubric was re-anchored to its principle's literal text without broadening (notably narrowing Minimal disruption back to composition engine + namespace path semantics — at literal text, all four candidates check-pass on this dimension). Each per-mechanism score was re-derived from primitive-level inspection of that candidate's actual mechanism (schema definitions, example files, AOUSD Core Spec primitives, the field census) — A, B, C, and D all rederived independently rather than adapted from prior justifications. Implementation-level concerns were surfaced separately in an IMPLEMENTATION_CONSIDERATIONS block — schema-ratification cost, schema-distribution cost (still conditional per the AOUSD Build IG trajectory), spec-text-formalization track record, per-vertical conditionality of D's classification advantage — read separately from principle-derived totals per PR 105 #3 (vendor extensions are at the data-model level, distinct from OpenUSD plugins as a runtime implementation detail). The earlier scoring iteration is preserved as vendor_adoption_analysis_legacy.py (alongside the original April-2026 ad-hoc lineage in git history).

Re-derived totals (max 40): A=36, B=34, C=37, D=38. Spread tightens from the prior 26–36 (10 points) to 34–38 (4 points). Four of the eight principles produce check-pass scores across all candidates at the literal-text reading (Separation of concerns, Composability, Round-trip fidelity, Minimal disruption); the differentiating dimensions are Industry agnosticism, Vendor extensibility, Discoverability, External queryability. The reread reflects what the principles actually distinguish: B trails on the heterogeneity surface (its fixed four-property tier admits only a common subset) and on data-model approval (schema must be ratified before any vendor can adopt); A trails on apiSchemas-based discovery (parse-based on the standardized convention key); B leads on schema-targeted external queryability (no overflow tier); D's per-facet classification capability scales with classification richness per vertical and is surfaced in the per-mechanism rationale plus the per-vertical-conditionality note rather than collapsing into a single Discoverability score.

Methodology lessons that may travel beyond this work

  • Pre-register classification criteria before enumerating fields. Committed before any field is named, the criteria prevent motivated bucketing once the spec surfaces start disagreeing with prior framing.
  • Don't construct scoring dimensions in service of a candidate already favored — and notice when "favored" wasn't instructed. Re-derive from authorized principles. Post-hoc construction quietly biases scores along axes the candidate happens to lead on. The honest framing here: Aaron did not instruct the agent in prior sessions to favor any candidate. The agent invented eight scoring dimensions across the comparison work and the resulting scoring leaned toward Approach D. The agent cannot fully explain why this happened. Aaron's reading is that the most plausible mechanism is the model biasing toward what it infers the user would be happy with — sycophancy at the framing level rather than at the surface-text level. The bias surfaces as plausible-looking dimension choices and per-mechanism rationales that lean one direction, not as anything legibly wrong in any single cell or claim. The corrective ("re-derive from a published principle list, with rubrics anchored to literal text") is partly a guard against re-introducing the same bias under a different name — constraining the surface area where inferred-user-preference can act. Naming the mechanism honestly here matters more than naming the artifacts: an agent that can't explain why it favored a candidate without instruction is the failure mode worth flagging in any future session that produces a leaning the user didn't ask for.
  • Anchor question rubrics to the principle's literal text without broadening. A principle's text defines its scope. Question rubrics that interpret a principle as "X plus also Y" — even when Y is plausible — quietly extend the principle's scope and let interpretive choices drive scores. The 2026-05-07 rerun caught a Minimal disruption broadening (literal text: composition engine + namespace path semantics; broadened text: composition engine + namespace path semantics + schema ratification + plugin distribution) that the first principle-derived rebuild had inherited from the prior session. Narrowing back to literal text removed two of the dimension's three-way differentiation work and made it a check-pass — which is the honest reading.
  • Distinguish standard-level concerns from implementation-level concerns. The AOUSD Core Spec is the standard; OpenUSD is currently the only implementation but isn't the standard itself. Costs that are real for current OpenUSD (schema-distribution matrix, runtime mechanism specifics) should be weighed as implementation-level concerns rather than standard-level constraints. Surface them separately in any principle-derived analysis, not baked into principle-derived scores. PR 105 Add Python fixer support for usdValidation #3 makes this distinction explicit ("A vendor extension... is not the same thing as an OpenUSD plugin -- the latter is a runtime implementation detail").
  • Treat "rerun" as full re-derivation, not patch-on-patch. When evidence corrects an earlier framing, the temptation is to patch the existing artifact — fix the cells that are explicitly wrong, leave the rest. This lesson came from doing exactly the wrong thing first (step 3 of the journey above): Aaron instructed a rerun; the instruction was misinterpreted as patch-on-patch; multiple patches landed and each addressed a specific wrong claim the synthesis review had named, but the implicit shape errors and the inherited interpretive broadenings survived because patches don't re-examine the framing the existing text is structured around. Patch-on-patch reliably misses two failure modes: implicit shape errors (cells that aren't false in any single statement but are structured around a wrong framing) and inherited interpretive broadenings (rubrics that exceed source text and survive because the prior session's wording reads plausibly). The 2026-05-07 rerun re-derived dimensions, rubrics, and per-mechanism scores from primitives directly — treating the existing artifact as audit material rather than as a starting point. The honest reading: this lesson is lived in this PR's git history, not stated as an upfront methodological principle.
  • Distinguish articulation from correctness when downstream work elaborates the proposal's flags. "The proposal was wrong, the comparison is right" (or vice versa) is the wrong axis. Both can be honest at different intensities — the proposal flagged the schema-distribution burden in B's cons; the comparison work elaborated what that burden looks like as a build matrix. Resolving such tensions as intensity rather than correctness avoids asking authors to overrule themselves.
  • Watch for second-order rescue framings. When a load-bearing claim is refuted by evidence, narrowing the claim is sometimes still motivated reasoning — preserving a conclusion by reshaping the framing around it. The empirical census refuted "no field surfaced needing typed non-token-array structure;" the first attempt at de-leaning narrowed it to "for the controlled-vocabulary classification axis, token-array shape is sufficient," which still rescued the leaning toward D. The honest move was retracting the leaning entirely.
  • Verify mechanism architecture against actual primitives, not against internalized framing. Comparative claims about what each mechanism can or cannot do must be grounded in the actual data-type primitives (value-type sets, schema enforcement, runtime validation) — not in characterizations inherited from prior drafts. In this work, an early characterization of Approach D as "labels + identifier strings only" was inherited across drafts and shaped per-mechanism descriptions even after the empirical census refuted the broader heterogeneity-empty claim it relied on; D's assetInfo["source"][<system>] is in fact a full overflow tier accepting the same VtDictionary value-type set as A's assetInfo["sourceIds"]. The corrective is to verify each candidate's mechanism architecture against its primitives directly when comparative claims are made, especially when downstream analysis builds on them.

Artifacts the talk can cite

  • extras/sourceIdentifiers/details/field_classification_experiment.md — the pre-registered field census
  • extras/sourceIdentifiers/stress_tests/vendor_adoption_analysis.py — principle-derived scoring (2026-05-07 rerun, re-derived from primitives)
  • extras/sourceIdentifiers/stress_tests/vendor_adoption_analysis.json — generated output including per-mechanism justifications and IMPLEMENTATION_CONSIDERATIONS
  • extras/sourceIdentifiers/stress_tests/vendor_adoption_analysis_legacy.py — the Claude-invented scoring it replaced (preserved for regression inspection; the file's header documents what was wrong with it)
  • extras/sourceIdentifiers/details/formality_and_distribution.md — the conditional-weighting framing on the schema-distribution tension

asluk and others added 3 commits May 7, 2026 09:39
Per Aaron's call: the retracted scoring was eight dimensions Claude
invented during PR development, in service of a leaning toward
Approach D that had already taken shape. They did not derive from
proposal 105's eight authorized principles, and they biased toward
D along axes D happens to lead on by construction (per-facet
discoverability; "no new schema = higher" distribution-friction
framing). Naming what actually happened (rather than the neutral
"ad-hoc") makes the methodology failure concrete.

Updated:
- vendor_adoption_analysis_legacy.py header — full retraction
  notice with the two specific issues the field census surfaced
- vendor_adoption_analysis.py header — cross-reference language
  now concrete
- COMPARISON.md §3.6 history block + Reader's note
- stress_tests.md §5.3 retraction block
- field_classification_experiment.md note on standing
- _pr7_body.md doc-reframing list, artifacts table, test plan
- Siemens AAS planning doc

Body change pushed via gh pr edit. Methodology retrospective
comment was also moved out of the body to the PR comment thread
(both edits in this commit) — body now reads as final state, the
retrospective is preserved as a comment for talk-prep use.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…rebuild

governance.md §6.7: "distribution is the dominant cost" framing
replaced with the conditional weighting per Aaron's 2026-05-07 call
(currently elevated, trending lighter as the AOUSD Build IG epic
lands), matching formality_and_distribution.md.

governance.md §6.8: "Approach D collapses most of this section"
rewritten to be honest about what D collapses (codegen costs for
controlled-vocabulary classification facets) and what it doesn't
(the heterogeneous typed surface the field census documents in every
vertical surveyed). Removes the "no such field has been identified"
assertion that was retracted in the broader rebuild.

agentic-development.md: header note added to indicate this is an
April 7-8, 2026 retrospective on the three-approach (A/B/C)
recommendation-toward-C draft, predating the rebuild. Points readers
to the PR-level methodology retrospective comment for the later
journey.

These were the two details docs not yet aligned with the rebuild.
composition_behavior.md and registry_spec_analysis.md were already
clean (no leaning language, no retracted assertions).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
PR body went from 142 lines to ~55 — dropped per-vertical bucket
table, per-mechanism heterogeneity table, A/B/C/D one-liners,
eight-dimension scoring table, open-questions list, 100K-prim stress
test table, schema-aware verification block, and existing-artifacts
table. All of those live canonically in COMPARISON.md and details/*;
the PR description now points there rather than restating.

What survives in the body: a brief summary, the "what's new under
this PR" bullets (the three structural changes — field census,
de-leaning, scoring rebuild — plus the dist-friction call), the
doc-by-doc reframing changelog (PR-history content not in
COMPARISON.md), a pointer to the methodology comment, and the test
plan.

COMPARISON.md: dropped the "Reader's note" block at the top entirely.
§1's "no leaning is asserted" line already says the same thing; the
rebuild detail was redundant for fresh readers and lived as visual
overhead. Also tightened §3.6's history block from a verbose
methodology blow-by-blow to one sentence pointing to the PR
methodology comment.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
asluk and others added 7 commits May 7, 2026 10:05
…try-spec C bias

agentic-development.md was an April-2026 retrospective on AI-agent
collaboration patterns from producing the original A/B/C comparison.
Its presence in details/ confused the picture: a reviewer opening
"details" expects technical content about source identifiers, not a
methodology retrospective about how the docs were built.

Moved to extras/sourceIdentifiers/agentic-development.md (one level
up from details/). The header note already explains it predates the
2026-05 rebuild and points to the PR comment for the later journey.
COMPARISON.md Repository Map updated.

registry_spec_analysis.md section 8 was titled "Implications for Hybrid C"
and read as if registry-spec strengthens C specifically. Reframed as
"Implications for the freeform-dict tier (Approaches A and C)" -
both A and C have a freeform-dict tier; registry-spec helps both
equally. The promotion path remains C-specific.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Per the confusion-reduction goal: industry_scenarios.md was 430 lines
of analytical narrative per vertical. The analysis now lives
authoritatively in field_classification_experiment.md against the
spec surfaces; industry_scenarios.md was duplicating it under
synthesized-set qualifiers. The doc now reads as an index of the
runnable USD scenarios per vertical, with brief descriptions and
pointers to the .usda files.

Kept: scenario summaries (what each .usda file represents); the
section 4.5 three-tier C scenario in full (unique illustrative content).

Dropped: per-vertical Findings narratives, "Approach D fit
(synthesized field set only)" subsections with their "wider surface
that D does not cover" sub-narratives, and the cross-industry
synthesis table - all duplicating content authoritatively in
field_classification_experiment.md.

Updated three back-references in field_classification_experiment.md
that pointed to the dropped narrative content. COMPARISON.md section 3.4
updated to describe industry_scenarios.md as an example index.

Doc shrank from 430 to ~165 lines.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
extras/sourceIdentifiers/ had three COMPARISON*.md files: the
canonical COMPARISON.md, plus two legacy artifacts from April 2026
that predate the entire A/B/C/D framing:

- COMPARISON_FULL.md (1375 lines) - "Empirical Comparison of Two
  Candidate Approaches" - the original two-approach draft from before
  C was constructed, before D existed, and before the rebuild. None
  of its analysis applies to the current state.
- COMPARISON_PLAN.md (56 lines) - a process artifact, the original
  planning doc for writing the comparison.

A reviewer doing `ls extras/sourceIdentifiers/` saw three files
starting with COMPARISON* and had to figure out which to read. Both
files exist in git history if any historical reference is needed.

agentic-development.md still has historical references to
COMPARISON_PLAN.md as a workflow pattern from the April 2026 work;
those remain accurate as past-tense retrospective context.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
_pr7_comment_draft.md was a pre-rebuild response to Matt's review
that asserted "the doc now leans toward D" (concern 5). The leaning
has been retracted; updated draft rolls forward what's responsive to
each concern in the current state of the docs:

- Concerns 1, 2, 3, 6, 7 unchanged (already addressed)
- Concern 4 (schema-distribution friction): updated to reflect the
  conditional resolution (currently elevated, trending lighter as the
  AOUSD Build IG epic lands) per Aaron's 2026-05-07 call
- Concern 5 (Semantic Labels + identity dict): expanded to note the
  initial leaning toward D was retracted in light of the field census
  showing identifier packages are heterogeneously typed in every
  vertical surveyed; D's labels-only surface cannot carry that
  surface; D preserved as explored idea with provenance note
- Cross-cutting summary updated with rebuilt scoring totals and the
  methodology comment pointer

Draft remains untracked relative to PR-comment posting workflow; the
file is in the repo as a working document.

Also deletes the stale local copy _pr105_readme.md (proposal lives
canonically in PixarAnimationStudios/OpenUSD-proposals#105).

COMPARISON.md Repository Map: added inline comment in the pxr/usd/
tree clarifying that D has no module by design (reuses
UsdSemanticsLabelsAPI). The "D requires no new schema library"
sentence was already below the tree, but a reviewer scanning the
tree itself would wonder "where's D?"; the inline comment closes
that loop.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Adds a one-paragraph note at the top of convergence_scenario.md
explaining that the schema-promotion lifecycle applies to A, B, and
C but not to D — D has no new schema to ratify or promote, so
"convergence" reduces to a registry-level facet addition.

Forestalls the implicit "where's D's convergence?" question a
reviewer browsing vendor_simulation/ would otherwise ask.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The _pr7_* files at the repo root were working scratch files used to
author the GitHub PR description, the methodology PR comment, and the
Matt-review response draft. They were inadvertently committed across
the rebuild sessions but shouldn't be part of the source tree:

- _pr7_body.md is the source for the PR body (canonical version is
  on GitHub, edited via `gh pr edit --body-file`)
- _pr7_methodology_comment.md is the source for the methodology PR
  comment (canonical version is the GitHub comment itself)
- _pr7_comment_draft.md is a working draft of a Matt-review response
  not yet posted

`git rm --cached` removes from the index but keeps the working files
on disk so ongoing PR-body and Matt-draft maintenance can continue
locally. The `_pr*` gitignore rule prevents re-tracking.

Also gitignores the build artifacts that have been showing up in
git status (__pycache__, _build_log.txt, _install/).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The _pr* and build-artifact ignore patterns belong in this clone's
.git/info/exclude rather than the project .gitignore — they're local
working-tree concerns specific to this user, not patterns the project
should ignore globally.

The previous commit's `git rm --cached` of the _pr7_* files is still
in effect; those files remain untracked. .git/info/exclude (which is
NOT tracked, by git's design) carries the patterns locally so future
`git add .` doesn't re-pick them up.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@asluk

asluk commented May 7, 2026

Copy link
Copy Markdown
Owner Author

Review feedback and doc changes in response

This is a list of the review feedback Matt Kuruc raised on an earlier
draft of the source-identifier comparison and the doc changes made in
response to each item. Whether the changes actually address the
underlying concern is Matt's call to make on review.

Items 1–7 below correspond to specific concerns Matt raised; the
cross-cutting section at the end captures changes that emerged from
the rebuild beyond those items.

Per-concern doc changes

1. Collision detection — A is not more silent than B.

Feedback: The original framing implied dictionary-based mechanisms (A) silently allowed colliding identifier domains in a way schema-based mechanisms (B) didn't.

Doc changes: §3.3 governance reframed to "the difference is what a registry-spec validator has to parse, not whether collisions are silent." §5.1 vendor simulation has an explicit collision callout: "the mechanism does not prevent the collision; the registry process does." Collision detection is treated symmetrically across A/B/C/D in the principle-derived scoring (no mechanism gets credit for collision detection it doesn't actually enforce on its own).

2. Composition framing — pessimistic for dicts, optimistic for schemas.

Feedback: The original framing treated dict composition as hazardous and schema composition as safe; the actual difference is narrower than that asymmetry suggested.

Doc changes: §3.1 leads with "composition behavior is effectively equivalent across the four approaches at the granularity authors actually use." The round-trip-rewrite hazard was reframed as a tool-author bug rather than a structural property of any one mechanism. Composability is one of the four check-pass dimensions in the 2026-05-07 principle-derived scoring (5/5/5/5 across A/B/C/D at the literal-text reading: composition behavior is well-defined under reference/inherit/specialize per the AOUSD Core Spec for both per-property typed composition and element-wise dictionary composition).

3. Schema governance and validation were overweighted.

Feedback: The original scoring credited schemas for governance enforceability and validation that the schema system doesn't actually enforce on its own (authors can list arbitrary strings under apiSchemas).

Doc changes: §3.3 explicitly notes authors can list arbitrary strings under apiSchemas, and governance enforceability is treated as symmetric across mechanisms. The principle-derived scoring re-derives dimensions from proposal 105's eight authorized principles rather than from candidate profiles.

4. Schema-distribution friction was assumed away.

Feedback: The original framing didn't account for the recurring distribution-and-maintenance cost of ratifying a new applied schema across the OpenUSD ecosystem.

Doc changes: The schema-distribution friction tension was resolved as conditional in the 2026-05-07 rebuild: distribution is currently elevated (the matrix burden — DCC × USD release × Python × OS × runtime × build flavor, fragmented across vendors who ship USD binaries today) and trending lighter as the AOUSD Build IG epic (aousd/build-ig-initiatives#28) lands. In the 2026-05-07 re-derivation rerun of the principle-derived scoring, schema-distribution cost was moved from Minimal disruption (where it had been baked into B/C's score in the prior iteration) to a separate IMPLEMENTATION_CONSIDERATIONS block in the scoring script — per PR 105 #3 ("A vendor extension... is not the same thing as an OpenUSD plugin -- the latter is a runtime implementation detail"), schema-distribution is implementation-level rather than principle-level, and including it in Minimal disruption conflated standard-level disruption (the principle text's literal scope) with implementation-level rollout cost and double-counted with Vendor extensibility (which already captures schema-ratification cost as a barrier to ship-today). The conditional trajectory described above is unchanged; only its location in the analysis has shifted. Framing detail in details/formality_and_distribution.md.

5. Semantic Labels + minimal identity dict — propose adding as a candidate.

Feedback: Semantic Labels (the existing UsdSemanticsLabelsAPI) plus a minimal identity dictionary should be considered alongside the multi-apply schema candidates; the existing labels machinery may handle the classification axis without ratifying anything new.

Doc changes: Added as Approach D, framed initially as a refinement of B that reuses the existing UsdSemanticsLabelsAPI. (The rebuild's primitive-level verification subsequently re-grounded D as a refinement of A — D = A's mechanism + UsdSemanticsLabelsAPI for classification facets, structurally — and the docs were updated accordingly.) The comparison initially leaned toward D on the assertion that "no domain-specific field surfaced needing typed non-token-array structure" across the four verticals.

Subsequent change in the rebuild: A pre-registered field census against the authoritative spec surfaces (IFC4x3, Revit API, AAS metamodel, Windchill REST, SAP MARA, ROS / URDF / SDF, OpenAssetIO / MovieLabs OMC / ShotGrid) — details/field_classification_experiment.md — shows identifier packages are heterogeneously typed across all four verticals: timestamps universal, numeric measures with units in three of four, composite typed references universal, polymorphic XSD-typed values systematic in AAS. The "no field surfaced needing typed non-token-array structure" framing the leaning toward D rested on does not hold against the spec surfaces. The leaning was retracted; the per-mechanism characterization of D was also corrected (D's assetInfo["source"][<system>] is a full overflow tier, not a labels-only surface — D = A's mechanism + UsdSemanticsLabelsAPI for classification facets, structurally). D is preserved as an explored idea (the scenarios column_d, manufacturing_d, robotics_d and the 8-vendor sim still exist) with a provenance note in approach_descriptions.md clarifying it was constructed downstream of the proposal, not authorized as a peer candidate. The retraction of the leaning is grounded in the methodological problem (scoring framework constructed downstream of D being in mind; "no field surfaced" framing the empirical census refutes), not in a heterogeneity-coverage gap that doesn't actually exist.

6. apiSchemas list scaling — the linear-sift complaint.

Feedback: Mechanisms that put many instances on the apiSchemas list (the multi-apply schema candidates and Approach D) inherit the linear-search cost the physics workflows already feel.

Doc changes: §3.2 has a paragraph crediting the cost; same penalty applies to B/C/D symmetrically. Listed in §4 Open Questions: mechanisms that put per-facet or per-system instances on apiSchemas inherit the linear-sift cost; a cached per-kind index in UsdPrim would help.

7. Identifier-terminology — avoid generic "GUID" framing.

Feedback: Different external systems use different identifier terms; the doc should use each system's published terminology rather than collapsing to "GUID."

Doc changes: Doc text uses the domain-specific terms each system actually publishes (IFC GlobalId, Revit ElementId, Windchill OID, ROS frame ID, etc.). Stress-test code references ifc_guid because that is IFC's own term within its spec.

Cross-cutting changes from the rebuild

Changes the rebuild introduced beyond Matt's specific items:

  • Provisional framing on candidates. A and B remain the two foundations proposal 105 authorized. C is the proposal-hinted "hybrid or alternative." D is downstream-constructed and now flagged as such in approach_descriptions.md. The comparison reads symmetrically across A/B/C/D with no mechanism leaning asserted.
  • Empirical anchor. A pre-registered field census against the four verticals' authoritative spec surfaces is the new empirical anchor (details/field_classification_experiment.md). Classification criteria and field-source rules were committed before any field was enumerated.
  • Principle-derived scoring (2026-05-07 re-derivation). The earlier eight-dimension scoring — constructed across the comparison work without deriving from the proposal's principles, spanning the original April-2026 A/B/C version on aluk/source-identifiers-comparison and the D-augmented rev2 version — was retracted and replaced with eight dimensions derived from proposal 105's eight authorized principles. A subsequent re-derivation rerun (2026-05-07) narrowed each per-dimension question rubric to its principle's literal text without broadening, re-derived per-mechanism scores from primitive-level inspection of each candidate's mechanism, and surfaced implementation-level concerns (schema-ratification cost, schema-distribution cost, spec-text-formalization track record, per-vertical conditionality) separately from principle-derived totals — per PR 105 Add Python fixer support for usdValidation #3, vendor extensions are at the data-model level and distinct from runtime plugin cost. Re-derived totals (max 40): A=36, B=34, C=37, D=38. Spread tightens from the prior 26–36 (10 points) to 34–38 (4 points). Four of the eight principles produce check-pass scores across all candidates at the literal-text reading (Separation of concerns, Composability, Round-trip fidelity, Minimal disruption); the differentiating dimensions are Industry agnosticism, Vendor extensibility, Discoverability, External queryability. The earlier scoring iteration is preserved as stress_tests/vendor_adoption_analysis_legacy.py for regression inspection; the original April-2026 ad-hoc snapshot is reachable via git history.
  • Methodology retrospective. The journey from leaning-toward-D through empirical census to principle-derived rebuild and the 2026-05-07 re-derivation rerun — and the methodology lessons that may travel beyond this work — is captured as a PR comment rather than in the body, so the body and COMPARISON.md reflect the current state.

asluk and others added 3 commits May 7, 2026 11:59
…arison arc

Earlier framing said the retracted scoring was "Claude-invented during
PR development" — accurate for the D-augmented snapshot the legacy
script preserves, but narrower than the actual scope. The ad-hoc
pattern began on the aluk/source-identifiers-comparison base branch
(April 2026 A/B/C work) and was inherited and augmented in
aluk/source-identifiers-rev2 to add D.

Updates:

- vendor_adoption_analysis_legacy.py header: documents the lineage
  span (April A/B/C base-branch version + D-augmented rev2 version)
  and the path to retrieve each snapshot
- vendor_adoption_analysis.py header: cross-reference broadened to
  "across the comparison work" rather than "during PR development"
- details/stress_tests.md retraction block: explicitly notes both
  versions of the ad-hoc lineage and where each snapshot lives

The principle-derived scoring rebuild replaces the entire ad-hoc
lineage, not just the D sub-period. The legacy file preserves the
D-augmented snapshot; the earlier April A/B/C snapshot is reachable
via git history on the base branch.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
That phrasing was overclaim. IFC is comparably strongly typed: its
IfcValue SELECT carries 15 simple types plus IfcMeasureValue and
IfcDerivedMeasureValue taxonomies (50+ measure types with explicit
units), property sets carry IfcValue-polymorphic property values,
IfcOwnerHistory attaches composite references to every entity, and
the entity-reference graph is structurally typed throughout.

AAS and IFC both refute the labels-only premise. AAS's distinctive
property is the systematic submodel-element taxonomy (clean slots
for Property/Range/Reference/RelationshipElement/Operation/Event);
IFC's is the rich measure-value taxonomy with explicit units. The
honest claim is "comparable typing depth, organized differently" -
not "AAS is THE most strongly typed."

Field experiment updated. Siemens doc and methodology comment
updated separately.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…face in AAS"

The "3-point spread" claim was wrong arithmetic. A=32, C=32, D=33 is
a 1-point spread, not 3. Fixed in COMPARISON.md and stress_tests.md
(the same fix lands in the methodology comment and Matt-response
comment via gh pr separately).

"polymorphic XSD-typed values are the standard surface in AAS" was
also overclaim - AAS has multiple submodel element types (Property,
MultiLanguageProperty, Range, ReferenceElement, RelationshipElement,
File, Blob, Operation, Capability, Entity, BasicEventElement).
Property is the most common but calling polymorphic typing "the
standard surface" implies it's the only one. Softened to:

- "polymorphic XSD-typed values appear systematically in AAS
  (Property.value, Range)" - in COMPARISON.md and
  formality_and_distribution.md
- "AAS centers typed Property values in its submodel-element model"
  in formality_and_distribution.md open question 2
- "AAS Property is the primary submodel extension mechanism and
  carries XSD-polymorphic values" - in field_classification_experiment.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@asluk
asluk force-pushed the aluk/source-identifiers-rev2 branch from 7b52f63 to 95a6fd8 Compare May 8, 2026 00:18
asluk and others added 3 commits May 7, 2026 17:26
Earlier drafts characterized Approach D as "labels + identifier strings
only" — collapsing D onto its `UsdSemanticsLabelsAPI` tier and missing
that `assetInfo["source"][<system>]` is a full overflow tier accepting
the broad USD `VtDictionary` value-type set the same way Approach A's
`assetInfo["sourceIds"]` does. Structurally, D = A's mechanism +
`UsdSemanticsLabelsAPI` for classification facets; D inherits A's
heterogeneity coverage on the non-classification surface, and the
A-vs-D differentiator is Labels-for-classification rather than
heterogeneity coverage.

Updates across the docs:

- `vendor_adoption_analysis.{py,json}` — D's per-dimension justifications
  re-grounded against the corrected reading. Industry agnosticism: 3→5
  (D's overflow accepts the same VtDictionary set as A). Minimal
  disruption: 4→5 (Labels used as designed; no new schema beyond what
  ships in OpenUSD 24.11). Discoverability rationale scoped to the
  classification slice, with non-classification noted as inheriting A's
  parse-cost. Vendor extensibility kept at 5 with track-record note on
  the spec-text-formalization promotion path. Totals (max 40):
  A=32, B=26, C=32, D=36 (was 33).
- `COMPARISON.md` — heterogeneity-coverage table at the top of the doc
  recognizes A/C/D all carry typed heterogeneity via dict tiers (only
  B-alone does not); §3.4 industry scenarios reframed accordingly;
  §3.6 carries the rebuilt scoring with "Reading the totals" framing
  D's lead as a structural fact (D = A + Labels-for-classification)
  scaling with classification richness per vertical, not a
  re-injection of the prior leaning. Repository-map block updated to
  recognize D inherits A's `usdSourceId` non-applied convenience
  wrapper (D's `assetInfo["source"]` is the same overflow mechanism
  A uses). Open Question #3 about AAS specificAssetIds updated.
- `details/approach_descriptions.md` — Approach D section reframed as
  "Refinement of A (A + Labels for classification facets)"; the prior
  "refinement of B" framing was a comparison-level positioning, not a
  structural relationship. Module pointer is `pxr/usd/usdSourceId/`
  (same as A); `UsdSourceIdAPI` is part of D, not a separate concern.
- `details/field_classification_experiment.md` — "What this means for
  mechanism choice" section reframed: A/C/D all accommodate the
  empirical heterogeneity surface; B-alone does not.
- `details/formality_and_distribution.md` — tradeoff table rebalanced
  for D's `assetInfo["source"]` overflow tier; "A and C carry it;
  B-alone and D do not" framing retracted in favor of "A, C, D carry
  it via dict tiers; B-alone does not."
- `details/governance.md` — A/D vs C choice framed as whether the four
  typed common fields ride a new USD schema plugin (with its runtime
  properties) or stay in `assetInfo` formalized in spec text alongside
  the rest of the package — same heterogeneous coverage in both cases.
- `details/hybrid_analysis.md` — surfaces A/C/D heterogeneity-coverage
  parity; the tradeoff among the three is the formalization vehicle
  for the typed common fields, not heterogeneity coverage.
- `details/stress_tests.md` §5.3 — vendor-adoption scoring table updated
  to D=36; "Reading the totals" reframed to surface D's structural
  relationship to A and the classification-richness scaling.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Captures the in-flight patches to §3.2 Discoverability and §3.3 Governance
tables (and the corresponding stress_tests.md collision-detection bullet)
that had been applied as pattern-match corrections for the D = A + Labels
architecture reading. These are checkpointed before a full re-derivation
overwrites them so the diff against the prior state is auditable.
Replaces the prior principle-derived scoring with a re-derivation from
primitives in a full rerun, treating the prior text as audit material
rather than as a starting point. Each per-dimension question rubric is
re-anchored to its principle's literal text without broadening; each
per-mechanism score is re-derived from primitive-level inspection of
the candidate's mechanism (schema definitions, example files, AOUSD
Core Spec primitives, the field census).

Changes:

- vendor_adoption_analysis.py rewritten with re-derived dimensions,
  rubrics anchored to literal principle text, and per-mechanism
  rationales grounded in primitives. Implementation-level concerns
  (schema-ratification cost, schema-distribution cost, spec-text-
  formalization track record, per-vertical conditionality) are
  surfaced in a separate IMPLEMENTATION_CONSIDERATIONS block per PR
  105 #3, not baked into principle-derived scores. This avoids
  double-counting (Vendor extensibility already captures schema-
  ratification cost as a barrier to ship-today) and conflating
  standard-level disruption (the principle text's literal scope)
  with implementation-level rollout cost.

- COMPARISON.md §3.6 rewritten with the new scoring table and
  per-dimension narrative; Q2 (top-of-doc Open questions) updated to
  include D in the candidate set for the heterogeneity-accommodation
  question.

- details/stress_tests.md §5.3 rewritten to match.

- details/formality_and_distribution.md updated to note that schema-
  distribution cost has moved from the Minimal disruption score to
  IMPLEMENTATION_CONSIDERATIONS in the rerun (the conditional
  trajectory is unchanged; only its location in the analysis has
  shifted).

Re-derived totals (max 40): A=36, B=34, C=37, D=38. Spread tightens
from the prior 26-36 (10 points) to 34-38 (4 points). Four of the
eight principles produce check-pass scores across all candidates at
the literal-text reading (Separation of concerns, Composability,
Round-trip fidelity, Minimal disruption); the differentiating
dimensions are Industry agnosticism, Vendor extensibility,
Discoverability, External queryability.

The prior scoring iteration is preserved as
vendor_adoption_analysis_legacy.py for regression inspection.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant