Establish InterfaceCanon with Statehub integration and FIAM-derived model
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a087be-d842-7252-81be-2105c4279c87
This commit is contained in:
parent
af74f742de
commit
ee0df5c931
21 changed files with 937 additions and 2 deletions
168
infospace/models/interface/InterfaceCanonInterfaceModel.md
Normal file
168
infospace/models/interface/InterfaceCanonInterfaceModel.md
Normal file
|
|
@ -0,0 +1,168 @@
|
|||
---
|
||||
id: interface-model
|
||||
title: InterfaceCanon Interface Model
|
||||
namespace: interface-model
|
||||
type: domain-model
|
||||
status: draft
|
||||
version: 0.1.0
|
||||
imports: [itc-land, itc-ident, itc-evid, itc-gov]
|
||||
import_manifest: imports.json
|
||||
source_manifest: ../../assimilation/fiam/sources.json
|
||||
---
|
||||
|
||||
# InterfaceCanon Interface Model
|
||||
|
||||
Draft terminology derived from FIAM v0.2 Draft 6. These are domain definitions,
|
||||
not a new FIAM schema or a claim of transferred ownership. The exact FIAM spellings
|
||||
and source JSON pointers are recorded below. [Upstream mappings](../../mappings/upstream.md)
|
||||
explain shared concepts and collisions; [imports.json](imports.json) pins InfoTechCanon.
|
||||
|
||||
## Structural vocabulary
|
||||
|
||||
Each source locator below is relative to `schemas/FIAM-Core-v0.2.schema.json`
|
||||
in the [pinned FIAM package](../../assimilation/fiam/README.md).
|
||||
|
||||
### 1. Port
|
||||
|
||||
An owned architectural participation point through which a participant or system node offers or requires a particular interface contract.
|
||||
|
||||
An offer/require mode is contract participation, not message direction.
|
||||
|
||||
Source: `#/$defs/port`. Local identifier: `interface-model:port`.
|
||||
|
||||
### 2. Contract Participation
|
||||
|
||||
The association of a Port with a specific InterfaceContract, an offers/requires mode, and contextual roles.
|
||||
|
||||
Roles belong to the participation; a port-global role cannot describe every contract context.
|
||||
|
||||
Source: `#/$defs/contractParticipation`. Local identifier: `interface-model:contractParticipation`.
|
||||
|
||||
### 3. Interface Contract
|
||||
|
||||
A semantic agreement organizing operations and their purposes independently of any particular transport realization.
|
||||
|
||||
One contract can have multiple bindings; a specification file describes the contract.
|
||||
|
||||
Source: `#/$defs/interfaceContract`. Local identifier: `interface-model:interfaceContract`.
|
||||
|
||||
### 4. Operation
|
||||
|
||||
A named unit of interface behavior within a contract, qualified by interaction style, temporal semantics, effects, and purpose.
|
||||
|
||||
A runtime exchange selects or realizes an operation; the operation is not a trace occurrence.
|
||||
|
||||
Source: `#/$defs/operation`. Local identifier: `interface-model:operation`.
|
||||
|
||||
### 5. Binding
|
||||
|
||||
A realization of a contract and selected operations through participating ports, communication stack, addressing, discovery, and optional channel or endpoints.
|
||||
|
||||
A second transport can realize the same contract without creating new semantic operations.
|
||||
|
||||
Source: `#/$defs/binding`. Local identifier: `interface-model:binding`.
|
||||
|
||||
### 6. Endpoint
|
||||
|
||||
A concrete locator or selector through which a Binding is reached.
|
||||
|
||||
An endpoint may be reused by multiple bindings; it is not the information resource selected through that binding.
|
||||
|
||||
Source: `#/$defs/endpoint`. Local identifier: `interface-model:endpoint`.
|
||||
|
||||
### 7. Channel
|
||||
|
||||
An exchange or mediation locus characterized by delivery, ordering, replay, or retention semantics where known.
|
||||
|
||||
A Kafka topic as exchange channel may be backed by a retained-log resource; those roles remain distinct.
|
||||
|
||||
Source: `#/$defs/channel`. Local identifier: `interface-model:channel`.
|
||||
|
||||
### 8. Interaction
|
||||
|
||||
An architectural participation in an exchange linking relevant operation, contract, binding, participants, and channel, with realization status where known.
|
||||
|
||||
An interaction can be proposed or rejected; do not equate every interaction with an executed span.
|
||||
|
||||
Source: `#/$defs/interaction`. Local identifier: `interface-model:interaction`.
|
||||
|
||||
### 9. Interaction Flow
|
||||
|
||||
An ordered composition of exchange steps referring to operations, interactions, bindings, and participants.
|
||||
|
||||
It expresses composition rather than inventing a new protocol or contract family.
|
||||
|
||||
Source: `#/$defs/interactionFlow`. Local identifier: `interface-model:interactionFlow`.
|
||||
|
||||
### 10. Information Resource
|
||||
|
||||
An identifiable information-bearing object, state, collection, or logical selection that can be addressed independently of a single interaction.
|
||||
|
||||
A collection is a resource; its admissible form is a shape, and its access location is not automatically a binding endpoint.
|
||||
|
||||
Source: `#/$defs/informationResource`. Local identifier: `interface-model:informationResource`.
|
||||
|
||||
### 11. Information Shape
|
||||
|
||||
An identifiable semantic or structural type or constraint set describing an admissible information form.
|
||||
|
||||
A shape is distinct from an instance, a schema artifact, and JSON or another concrete encoding. Detailed fields remain in describing artifacts.
|
||||
|
||||
Source: `#/$defs/informationShape`. Local identifier: `interface-model:informationShape`.
|
||||
|
||||
### 12. Resource Selector
|
||||
|
||||
A selector identifying an information resource within a provider, namespace, collection, or logical address space.
|
||||
|
||||
A database collection selector does not locate the network binding.
|
||||
|
||||
Source: `#/$defs/resourceSelector`. Local identifier: `interface-model:resourceSelector`.
|
||||
|
||||
## Facets and interpretations
|
||||
|
||||
A **Facet** records an orthogonal characteristic of a structural entity or assertion.
|
||||
FIAM uses controlled terms for such dimensions as interaction style, temporal
|
||||
semantics, effect, purpose, communication stack, and security. A facet is not a
|
||||
new structural interface type. Source: Core `#/$defs/facets` and the FIAM Canon.
|
||||
|
||||
**Representation** is the concrete encoding or notation selected for information
|
||||
participation. It is authoritative on the most specific applicable shape-participation
|
||||
assertion. Operation-level and contract-level representation lists are deprecated.
|
||||
Source: Draft 1, “Representation stays relation-scoped”.
|
||||
|
||||
A **Lens** is a named interpretation over architectural facts and their evidence.
|
||||
**Family labels** are derived lens results, with inferred provenance if cached;
|
||||
HTTP, RPC, messaging, or a label such as REST must not become invented Core classes.
|
||||
Source: Draft 1, “Cached family labels require provenance”; Draft 6 §§1, 6–7.
|
||||
|
||||
## Relationships and invariants
|
||||
|
||||
- A Port participates in a contract; a Binding realizes that contract and its operations.
|
||||
- Shape participation refines Operation → Binding → Interaction. Refinement uses
|
||||
the same shape, identity-equivalent shape, or evidenced projection/version.
|
||||
Multi-operation binding refinements identify the operation with `operation_ref`.
|
||||
- `conforms-to-shape` describes the whole addressed resource; `element-shape`
|
||||
describes collection members. A collection's shape and its element shape differ.
|
||||
- Artifacts describe or implement architectural entities; representation encodes information.
|
||||
- Missing facts remain unknown. Explicit absence, not-applicable, and unknown differ.
|
||||
- Similarity supports correspondence, not automatic identity or destructive merging.
|
||||
- Lens evidence scores and governance conclusions remain policy-dependent results.
|
||||
|
||||
Sources: Draft 1 “Stable structural spine” and hardening decisions 3–7;
|
||||
Core `assertion`; Draft 6 §§1, 6–7. These summaries preserve source semantics;
|
||||
FIAM remains authoritative for exact validation requirements.
|
||||
|
||||
## Worked boundary cases
|
||||
|
||||
| Case | Interpretation |
|
||||
| --- | --- |
|
||||
| Same MCP tools over stdio and HTTP | Shared contract/operations/shapes; distinct realization bindings. |
|
||||
| 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. |
|
||||
| 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. |
|
||||
|
||||
These are explanatory cases derived from the pinned source, not executable FIAM
|
||||
fixtures or evidence of consumer adoption. Cross-canon review and a consumer proof
|
||||
are tracked in INTERFACE-WP-0003.
|
||||
Loading…
Add table
Add a link
Reference in a new issue