coulomb/interface-canon
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Apply InfoTechCanon acceptance consistently across mappings and examples

Browse source 
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a087be-d842-7252-81be-2105c4279c87
This commit is contained in:
tegwick 2026-09-09 23:06:06 +02:00
parent ae20bc631c
commit 6ae63977e7
7 changed files with 163 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

3
WORK-RECORDS.md
View file

@ -12,6 +12,7 @@
| workplan | INTERFACE-WP-0002 | finished | — | workplans/INTERFACE-WP-0002-canon-foundation.md |
| workplan | INTERFACE-WP-0003 | finished | — | workplans/INTERFACE-WP-0003-mapping-and-consumer-review.md |
| workplan | INTERFACE-WP-0004 | finished | — | workplans/INTERFACE-WP-0004-federation-acceptance.md |
| workplan | INTERFACE-WP-0005 | finished | — | workplans/INTERFACE-WP-0005-infotech-clarification-follow-through.md |
| task | INTERFACE-WP-0001-T01 | done | — | workplans/INTERFACE-WP-0001-statehub-bootstrap.md |
| task | INTERFACE-WP-0001-T02 | done | — | workplans/INTERFACE-WP-0001-statehub-bootstrap.md |
| task | INTERFACE-WP-0001-T03 | done | — | workplans/INTERFACE-WP-0001-statehub-bootstrap.md |
@ -23,3 +24,5 @@
| task | INTERFACE-WP-0003-T03 | done | — | workplans/INTERFACE-WP-0003-mapping-and-consumer-review.md |
| task | INTERFACE-WP-0004-T01 | done | — | workplans/INTERFACE-WP-0004-federation-acceptance.md |
| task | INTERFACE-WP-0004-T02 | done | — | workplans/INTERFACE-WP-0004-federation-acceptance.md |
| task | INTERFACE-WP-0005-T01 | done | — | workplans/INTERFACE-WP-0005-infotech-clarification-follow-through.md |
| task | INTERFACE-WP-0005-T02 | done | — | workplans/INTERFACE-WP-0005-infotech-clarification-follow-through.md |

30
infospace/examples/repo-manager-statehub.md
View file

@ -15,7 +15,7 @@ is limited to this interface description and reviewed model 0.1.1.
| Concept | Concrete interpretation | Source evidence |
| --- | --- | --- |
| System nodes | Repo Manager client and primary Statehub API | Consumer client construction and provider primary-role check. |
| Ports / participations | Client requires repository-projection contract; Statehub offers it | Client POST and matching provider router. These are semantic ports, not TCP port numbers. |
| Ports / participations | Client requires repository-projection contract; Statehub offers it | Client POST and matching provider router. These are FIAM contract-participation ports, distinct from both physical/device and protocol-level transport network ports. |
| Interface Contract | Reconcile a repository's work-record projection from an exact pushed Forge commit | Provider compares derived commit with expected_commit before reset. |
| Operation | ReconcileRepositoryProjection | POST `/repos/{slug}/work-record-projection/reconcile`. HTTP method/path realizes the semantic operation. |
| Binding | JSON over the configured HTTP API base with idempotency and source-agent headers | `httpx.Client`, `json=`, `Idempotency-Key`, `X-StateHub-Source-Agent`. No HTTP version or TLS property is inferred. |
@ -66,3 +66,31 @@ the provider enforces equality with the derived Forge commit. The presence of an
Idempotency-Key header alone does not prove provider deduplication behavior.
Authentication, TLS, HTTP-version, and gateway properties remain unestablished by
this mapping. These limits match the committed Repo Manager acceptance record.
## InfoTechCanon clarification checks
Apply the [accepted mappings](../mappings/upstream.md) to this same integration:
- **Port and Interface:** the client requires a semantic contract. A host NIC
attachment and a TCP transport port describe network realization, not that
participation. Neither implies a second semantic contract.
- **Endpoint and resource:** the configured API locator reaches the Binding;
the repository slug selects persisted projection state. This HTTP example
cannot establish that every possible FIAM Binding has a Network Endpoint.
- **Resource and shape:** projected work records constitute addressed state;
the request's field constraints describe admissible input. Dataset, Record,
DataType, and Constraint are contextual ITC mappings, not blanket replacements.
- **Representation:** the request uses JSON encoding. `acknowledge_retirements`
has a boolean value form. These representation scopes are compatible but
distinct; neither the field's false value nor its JSON bytes is a new shape.
- **Artifact and knowledge:** the schema source can describe reusable interface
knowledge. The client implementation is a FIAM Artifact implementing behavior;
that role alone does not classify it as KnowledgeArtifact.
- **Evidence:** the pinned provider schema Git blob is an addressable Evidence
Source with a version. For the explicit interest “which commit references can
the request accept?”, the assertion “expected_commit accepts a full 40-hex SHA”
is separate Evidence, located at `RepositoryProjectionReconcile.validate_commit`.
A future mutable schema page would additionally need a version or capture.
These are meaning checks for the existing example, not new implementation facts,
FIAM wire records, or an assertion of complete cross-canon equivalence.

42
infospace/mappings/infotech-follow-through.md Normal file
View file

@ -0,0 +1,42 @@
# InfoTechCanon clarification follow-through
Request: the user supplied InfoTechCanon's focused request on 2026-09-09 to apply
accepted clarifications, link acceptance commit f921e5a, and check examples.
Workplan: INTERFACE-WP-0005. No full review restart is needed.
The acceptance record was already pinned, and part of the clarification text was
already implemented in 0.1.2. This pass completes its propagation into the main
mapping table and makes the example checks explicit. It preserves the existing
model definitions and seven InfoTechCanon import pins, FIAM source pins, draft
0.1.2 version, and the owners' original 0.1.1 review targets. This is documentation
follow-through, not a semantic release or new owner approval.
## Traceability
All rows derive from the accepted dispositions in the
[owner record](../../../info-tech-canon/infospace/interfaces/interface-canon-boundary.md)
at `f921e5a543db8da49781bd560d303f780623d204`, verified through its
[immutable source manifest](../reviews/acceptance/info-tech-canon-sources.json).
FIAM locators below refer to the pinned Core in the
[FIAM source manifest](../assimilation/fiam/sources.json).
| Concern | Explicit mapping and example check | FIAM compatibility |
| --- | --- | --- |
| Port | Device port, transport port, and contract-participation Port remain distinct. Model NIC/TCP/service case and Repo Manager Port check. | `#/$defs/port`, `contractParticipation`: offered/required contract participation and contextual roles. |
| InterfaceContract | Semantic agreement is contextual to Landscape/Network Interface, with no universal alias. Repo Manager contract versus NIC case. | `#/$defs/interfaceContract`, `binding`: contract and realization remain separate. |
| Endpoint | Binding locator/selector differs from resource selector; stdio does not require a Network Endpoint. Model MCP stdio case and Repo Manager locator/slug check. | `#/$defs/endpoint`, `resourceSelector`, `binding`: endpoints optional on Binding; selector addresses information. |
| Resource/shape | Addressed projection state differs from admissible request form; ITC data terms retain scoped meanings. Repo Manager Resource/shape check and model JSON/schema case. | `#/$defs/informationResource`, `informationShape`: state independent of an interaction; form independent of resource/artifact/encoding. |
| Representation | JSON encoding differs from boolean value-level form. Model JSON/boolean case and Repo Manager request field check. | Draft 1 representation hardening: most-specific shape-participation assertion is authoritative. |
| Artifact/KnowledgeArtifact | Describing reusable knowledge may qualify; implementation alone is insufficient. Model schema/binary case and Repo Manager source roles. | `#/$defs/artifact`: distinct describes/implements roles without a universal knowledge-artifact assertion. |
| Evidence | Addressable versioned/captured source differs from assertion for an explicit interest. Model mutable-page case and Repo Manager expected_commit assertion. | `#/$defs/assertion`, `evidenceRecord`: assertion and support metadata retained; no one-to-one renaming into ITC Evidence. |
Checked surfaces: [main mappings](upstream.md),
[original mapping review with clarifications](review-2026-09-09.md),
[model boundary cases](../models/interface/InterfaceCanonInterfaceModel.md), and
[Repo Manager example](../examples/repo-manager-statehub.md).
Result: all seven mapping concerns from the accepted dispositions are explicit
and exercised by examples. No unresolved inconsistency was found within this
bounded request. This is not a claim that every concept in both canons has been
exhaustively aligned. Shared meanings stay upstream; FIAM retains standard and
conformance authority. No runtime behavior or peer definitions were changed.

7
infospace/mappings/review-2026-09-09.md
View file

@ -1,6 +1,7 @@
# Shared-concept review — 2026-09-09
Workplan: INTERFACE-WP-0003. Review scope: the initial model's structural terms
Original review: INTERFACE-WP-0003. The accepted-clarification follow-through is
recorded in [INTERFACE-WP-0005 evidence](infotech-follow-through.md). Review scope: the initial model's structural terms
and its explicit shared-root collisions. The [import manifest](../models/interface/imports.json)
pins the reviewed InfoTechCanon models; existing four source hashes are unchanged.
This review expands the mapping set with Data, Information Space, and Network.
@ -9,13 +10,13 @@ It records local semantic dispositions, not an upstream ownership transfer.
| Local/FIAM usage | Reviewed source section | Disposition and counterexample |
| --- | --- | --- |
| Interface Contract | ITC-LAND §13.2 Interface seed | Related specialization of interface architecture. A network attachment called Interface does not imply a semantic operation contract. |
| Port | ITC-NET §§11.26–11.27 Interface/Port | Distinct concepts. FIAM Port participates in a contract; TCP port 8000 is a transport selector. Never equate them by spelling. |
| Port | ITC-NET §§11.26–11.27 Interface/Port | Distinct concepts. FIAM Port participates in a contract; network Port includes physical/device ports and protocol-level transport ports. TCP port 8000 is one transport example. Never equate them by spelling. |
| Endpoint | ITC-LAND §13.2; ITC-NET §11.45 | FIAM-qualified locator of a Binding. A network ServiceEndpoint can realize that locator, but not all FIAM bindings are network-based. |
| Information Resource | ITC-DATA §§8.1–8.2, 11.4, 11.8–11.9 | Related to Dataset/DataObject/Record by modeled scope. A dataset is a coherent managed unit; FIAM also covers a resource selection or state locus. No universal subtype or exact-equivalence claim. |
| Information Shape | ITC-DATA §§8.3, 11.15–11.16 | Related to DataType/Constraint. Shape carries admissible semantic/structural form; a schema artifact describes details. A type name alone does not establish shape identity. |
| Representation | ITC-DATA §11.14 | FIAM specializes encoding/notation selected for shape participation. Data Representation also covers value-level forms such as integer or date. JSON does not establish a field's semantic type. |
| Artifact | ITC-INFOSPACE §11.8 KnowledgeArtifact | A schema or interface document carrying reusable knowledge qualifies as KnowledgeArtifact. A FIAM Artifact can also implement a contract, so no blanket equivalence. |
| Source provenance | ITC-INFOSPACE §§11.30–11.31; ITC-EVID §2 | Import Citation/SourceReference and Evidence Source. A Git blob is a source container; the claim extracted from it is separate Evidence. |
| Source provenance | ITC-INFOSPACE §§11.30–11.31; ITC-EVID §2 | Import Citation/SourceReference and Evidence Source. A Git blob is an addressable source container with a pinned revision; the claim extracted for an explicit interest is separate Evidence. Mutable sources need a relevant version/capture. |
| Assertion / evidenceRecord | ITC-GOV Assertion; ITC-EVID §§1–2 | FIAM property/relation assertion specializes architectural assertions. Its evidenceRecord supplies support metadata; model the ITC assertion, question, and source separately rather than renaming the record. |
| Identity correspondence | ITC-IDENT Synonymity Assertion; FIAM Draft 1 decision 7 | Similarity is a correspondence candidate; governed identity and non-destructive equivalence remain separate. |
| Participant / SystemNode | ITC-LAND §13.2 SoftwareSystem/SoftwareComponent | Context-dependent alignment. A logical system, deployed process, and Actor must not collapse solely because a name is shared. |

21
infospace/mappings/upstream.md
View file

@ -3,19 +3,29 @@
InfoTechCanon supplies shared semantics through the model's
[import manifest](../models/interface/imports.json). FIAM supplies the specialized
architecture vocabulary through its [source manifest](../assimilation/fiam/sources.json).
This is a draft local mapping; no upstream ownership transfer is asserted.
These mappings implement the accepted dispositions in InfoTechCanon's
[boundary acceptance record](../../../info-tech-canon/infospace/interfaces/interface-canon-boundary.md)
at commit `f921e5a543db8da49781bd560d303f780623d204`.
The [acceptance manifest](../reviews/acceptance/info-tech-canon-sources.json)
pins that exact Git blob; the sibling link is navigation to the current owner copy.
InfoTechCanon definitions and FIAM semantics remain unchanged. Compatibility
means explicit, compatible scopes; distinct concepts need not share one definition.
| FIAM/domain term | Shared owner or disposition | Mapping boundary |
| --- | --- | --- |
| InterfaceContract | Local interface specialization; ITC-LAND already seeds Interface | A semantic contract is one aspect of interface architecture; not an exact alias for every landscape Interface. |
| Endpoint | ITC-LAND seeds Endpoint; local FIAM-qualified usage | The FIAM meaning is the locator of a Binding. Network interfaces and resource selectors are separate. |
| Port | FIAM contract participation; ITC-NET retains network Port | Distinct meanings: a FIAM Port offers/requires a contract; network profiles distinguish physical/device ports from protocol-level transport ports. Neither is a universal alias for FIAM Port. |
| InterfaceContract | Interface-domain meaning derived from FIAM; ITC-LAND retains Interface seed | Semantic agreement over operations. Landscape Interface and Network attachment-point Interface are contextual mappings, not universal exact aliases or inferred subtype relationships. |
| Endpoint | ITC-LAND/ITC-NET shared context; FIAM-qualified usage | Locates or selects a Binding. Related to Network Endpoint for network realizations, but local bindings need not have a network endpoint. A resource selector identifies information within its provider scope instead. |
| Information Resource / Information Shape | FIAM interface-domain roles; ITC-DATA retains Dataset, DataObject, Record, DataType, Constraint | Contextual alignment according to addressed state and admissible form; no universal subtyping or exact equivalence. Detailed schema content stays in describing artifacts. |
| Representation | FIAM participation encoding; ITC-DATA retains value-level Representation | Qualify the scope: JSON is an encoding for shape participation; boolean or integer describes a value-level form. Encoding does not determine semantic type or shape identity. |
| Participant / SystemNode | Align with ITC-LAND SoftwareSystem/SoftwareComponent where applicable | No blanket equivalence to Actor, host, process, or deployment; choose by modeled scope. |
| Entity identifier | ITC-IDENT Identifier / Scoped Identifier | FIAM identifier syntax alone does not establish global identity. |
| same-entity-as | Relate to ITC-IDENT Synonymity Assertion | FIAM query-time equivalence has specific evidence constraints; no destructive merge or automatic cross-canon equivalence. |
| Assertion | ITC-GOV Assertion | FIAM specializes architectural property/relation assertions with evidence and polarity. |
| FIAM evidenceRecord | Map to ITC-EVID Evidence plus Evidence Source | FIAM evidenceRecord is support metadata with source, mode and confidence. ITC Evidence is an assertion drawn for a question; source container is separately identified. This is not a one-to-one rename. |
| Evidence score | ITC-EVID Evidence strength | A FIAM Lens computes a policy-specific heuristic; confidence and support scores are not universal truth probabilities. |
| Artifact | FIAM describing/implementing artifact role | It may serve as ITC Evidence Source when addressable and versioned/captured where mutable; the Evidence assertion must state its explicit interest. Implementing a contract does not automatically make an artifact a KnowledgeArtifact. |
| Artifact / KnowledgeArtifact | FIAM describes/implements roles; ITC-INFOSPACE retains KnowledgeArtifact | A describing document carrying reusable knowledge may qualify as KnowledgeArtifact. Merely implementing a contract does not establish that classification. |
| Evidence Source / Evidence | ITC-EVID shared meanings; FIAM assertion/support mapping | Evidence Source is an addressable container, with relevant version or capture where mutable. Evidence is a separate assertion drawn for an explicit interest. A FIAM evidenceRecord's support metadata is not automatically that ITC assertion. |
| Zone / security profile | Reference FIAM contextual classifications | No transfer of generic network, security, trust, tenant, or authorization ownership. |
| Policy / decision | ITC-GOV Policy / Decision | A Lens finding is an interpretation, not automatically a governed decision or authorization. |
@ -47,3 +57,6 @@ interest. These clarifications preserve the imported source meanings.
Acceptance scope and source revisions are recorded in the
[acceptance report](../reviews/acceptance/README.md). Earlier owner reviews target
0.1.1; the local clarification revision is draft 0.1.2.
The [focused follow-through](infotech-follow-through.md) traces each clarified
meaning to the checked examples and pinned FIAM evidence.

8
infospace/models/interface/InterfaceCanonInterfaceModel.md
View file

@ -163,6 +163,11 @@ FIAM remains authoritative for exact validation requirements.
| Kafka topic with retained events | Channel for exchange, Information Resource for retained log, related by `backed-by`. |
| JSON document governed by a schema | Resource instance, Information Shape, describing Artifact, and Representation remain distinct. |
| Port offers a request-response contract | Offers is participation mode; requests and responses still travel in different directions. |
| A physical NIC port, TCP port 8000, and a service's offered Port | Device/transport network meanings and FIAM contract participation remain distinct; equal names do not identify one concept. |
| MCP stdio binding has no network address | A local realization need not have a Network Endpoint; FIAM does not require a network locator for every Binding. |
| JSON encodes a boolean field | JSON is FIAM participation Representation; the value's boolean form is a distinct Data Representation concern. |
| A schema document and a binary both implement or describe an interface | Reusable schema knowledge may qualify as KnowledgeArtifact; implementation alone does not establish that classification for the binary. |
| A mutable schema page supports a claim about an accepted field | Capture the page version and locator as Evidence Source; separately state the field assertion and the explicit interest it supports. |
| Two schemas have identical fields | Correspondence candidate; no automatic identity assertion. |
| Telemetry contains no authentication attributes | Unknown runtime authentication evidence; no inferred absence of protection. |
@ -171,3 +176,6 @@ fixtures or evidence of consumer adoption. The [mapping review](../../mappings/r
[Repo Manager case](../../examples/repo-manager-statehub.md) complete the initial
review. Scoped external acceptance and adoption are recorded in completed
INTERFACE-WP-0004; see the [acceptance report](../../reviews/acceptance/README.md).
These cross-canon cases apply the [accepted mappings](../../mappings/upstream.md)
without equating distinct FIAM and InfoTechCanon concepts.

60
workplans/INTERFACE-WP-0005-infotech-clarification-follow-through.md Normal file
View file

@ -0,0 +1,60 @@
---
id: INTERFACE-WP-0005
type: workplan
title: "Apply InfoTechCanon clarifications consistently to mappings and examples"
domain: infotech
repo: interface-canon
status: finished
owner: codex
topic_slug: canon
created: "2026-09-09"
updated: "2026-09-09"
---
# InfoTechCanon clarification follow-through
Origin: request text supplied by the user on 2026-09-09. InfoTechCanon asks for
its accepted clarifications to appear in InterfaceCanon mappings, a link to
acceptance commit f921e5a, and consistent examples. Compatibility means explicit
meanings, not forced equivalence. This is a focused documentation follow-through;
InfoTechCanon definitions, FIAM source semantics, and prior review scopes stay
unchanged. No full review restart or stable promotion is required.
## Apply and trace the accepted clarifications
```task
id: INTERFACE-WP-0005-T01
status: done
priority: medium
```
Compare each disposition in the pinned acceptance with the main mapping table.
Fill omissions and link the owner record and immutable manifest. Done when all
seven mapping concerns from the accepted dispositions are explicit and compatible with the FIAM source.
## Check examples and document the result
```task
id: INTERFACE-WP-0005-T02
status: done
priority: medium
```
Check the model boundary cases and Repo Manager consumer example against those
dispositions. Add concrete counterexamples where needed and record traceability.
Validate links, source pins, and metadata; commit and synchronize the result.
No runtime changes or new semantic roots are in scope.
## Result
[Follow-through evidence](../infospace/mappings/infotech-follow-through.md) maps
all accepted concerns to explicit wording, checked examples, and pinned FIAM
locators. The main mapping table now includes the previously indirect Port,
Resource/Shape, and Representation distinctions and directly links the owner
acceptance record plus its immutable manifest. Existing examples were checked;
concrete network-port, stdio, value/encoding, artifact, and evidence cases were added.
No full review was restarted and no shared definition, original source pin,
publication status, or model version changed. Both tasks are complete with no
residuals from this focused request. Validation: source/link checks, pinned FIAM
locator checks, unchanged original import/source manifests, and metadata checks.