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.
|
||||
49
infospace/models/interface/imports.json
Normal file
49
infospace/models/interface/imports.json
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
{
|
||||
"schema_version": 1,
|
||||
"model": "interface-model",
|
||||
"source_repository": "info-tech-canon",
|
||||
"source_commit": "8eb1c83f2e119de57e7ad448b901381f8e92fb57",
|
||||
"imports": [
|
||||
{
|
||||
"model": "itc-land",
|
||||
"path": "infospace/models/landscape/InfoTechCanonLandscapeModel.md",
|
||||
"sha256": "4190b044fbd5e3eecf7b28e08608e99c7de3af5dd5f3a7554edee02423967fb1",
|
||||
"concepts": [
|
||||
"Interface",
|
||||
"Endpoint",
|
||||
"SoftwareSystem",
|
||||
"SoftwareComponent"
|
||||
]
|
||||
},
|
||||
{
|
||||
"model": "itc-ident",
|
||||
"path": "infospace/models/identity/InfoTechCanonIdentityModel.md",
|
||||
"sha256": "20bc844d9de07041c40009cc5e3d6eeb42aeb7adcbb86b0194d4b2517aa23f32",
|
||||
"concepts": [
|
||||
"Identifier",
|
||||
"Scoped Identifier",
|
||||
"Synonymity Assertion"
|
||||
]
|
||||
},
|
||||
{
|
||||
"model": "itc-evid",
|
||||
"path": "infospace/models/evidence/InfoTechCanonEvidenceModel.md",
|
||||
"sha256": "a93472818b3ae60c07a4c6226090d63eebf1402dfd9f46dad643dbb5608ed086",
|
||||
"concepts": [
|
||||
"Evidence",
|
||||
"Evidence Source",
|
||||
"Evidence strength"
|
||||
]
|
||||
},
|
||||
{
|
||||
"model": "itc-gov",
|
||||
"path": "infospace/models/governance/InfoTechCanonGovernanceModel.md",
|
||||
"sha256": "5f3174147ec0d6f5bb6479a7ce4dc130bf61ecc0bab3936895b92c6baf21deb5",
|
||||
"concepts": [
|
||||
"Assertion",
|
||||
"Policy",
|
||||
"Decision"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue