@n8r/surface 0.1.0-experimental.2 → 0.1.0-experimental.5

package/dist/contracts.d.ts

@@ -1,4 +1,4 @@
-/** Experimental 0.1 contracts, not a universal AI Surface Model schema. */
+/** Experimental bounded contracts, not a universal AI Surface Model schema. */
 export type Value = null | boolean | number | string | Value[] | {
     [key: string]: Value;
 };
@@ -126,4 +126,110 @@ export interface SurfaceDefinition extends Envelope {
     coverage: string[];
     gaps: string[];
 }
-export type Artefact = ResearchRecord | SurfaceDefinition;
+/** JSON-only descriptions; no settings values or opaque extensions in this profile. */
+export interface DescriptionNode {
+    id: string;
+    label: string;
+    type: {
+        vocabulary: string;
+        term: string;
+    };
+}
+export interface DescriptionEnvelope extends Envelope {
+    contract: 'n8r.surface/0.2';
+    records: RevisionRef[];
+    vocabularies: {
+        id: string;
+        version: string;
+    }[];
+    nodes: DescriptionNode[];
+    coverage: string[];
+    gaps: string[];
+}
+export interface CapabilitySurface extends DescriptionEnvelope {
+    kind: 'capability';
+    capabilities: {
+        id: string;
+        from: string;
+        to: string;
+        type: {
+            vocabulary: string;
+            term: string;
+        };
+        state: 'possible' | Exclude<State, 'known'> | 'conflicting';
+        basis: Basis[];
+        conditions: string[];
+        note: string;
+    }[];
+    exclusiveGroups: {
+        id: string;
+        members: string[];
+    }[];
+}
+export interface BoundSurface extends DescriptionEnvelope {
+    kind: 'bound';
+    capability: RevisionRef;
+    instance: {
+        id: string;
+        label: string;
+    };
+    bindings: {
+        id: string;
+        capability: string;
+        state: 'configured' | Exclude<State, 'known' | 'absent'> | 'conflicting';
+        claims: {
+            target: string;
+            basis: Basis[];
+        }[];
+        decisions: Basis[];
+        note: string;
+    }[];
+}
+export type SurfaceDescription = CapabilitySurface | BoundSurface;
+/** Shared node/edge contract; setting names and safe locations, never values. */
+export interface ConfigurationReference {
+    owner: string;
+    mechanism: 'environment-variable' | 'file-key' | 'argument' | 'admin-setting' | 'code';
+    key: string;
+    location: string;
+}
+export interface RelationshipDetail<T> {
+    state: State | 'conflicting';
+    claims: {
+        value: T;
+        basis: Basis[];
+    }[];
+    note: string;
+}
+export interface DescriptionRelationship {
+    id: string;
+    from: string;
+    to: string;
+    type: DescriptionNode['type'];
+    purpose: RelationshipDetail<string>;
+    integration: RelationshipDetail<string>;
+    configuration: RelationshipDetail<ConfigurationReference[]>;
+    basis: Basis[];
+    conditions: string[];
+    note: string;
+}
+export interface GraphEnvelope extends Omit<DescriptionEnvelope, 'contract'> {
+    contract: 'n8r.surface/0.3';
+}
+export interface CapabilityGraph extends GraphEnvelope {
+    kind: 'capability';
+    relationships: (DescriptionRelationship & {
+        state: CapabilitySurface['capabilities'][number]['state'];
+    })[];
+    exclusiveGroups: CapabilitySurface['exclusiveGroups'];
+}
+export interface BoundGraph extends GraphEnvelope {
+    kind: 'bound';
+    capability: RevisionRef;
+    instance: BoundSurface['instance'];
+    relationships: (DescriptionRelationship & {
+        binding: Omit<BoundSurface['bindings'][number], 'id' | 'capability'>;
+    })[];
+}
+export type SurfaceGraph = CapabilityGraph | BoundGraph;
+export type Artefact = ResearchRecord | SurfaceDefinition | SurfaceDescription | SurfaceGraph;