Software Design Specification (SDS)
Defines the Context Materialization Service (CMS) — a projection target that takes a canonical ContextSpec from the Semantic Core and produces a runnable ContextInstance with auditable provenance and governance evidence.
The Context Materialization Service is a projection engine, not a semantic editor. It takes canonical semantic specifications and materializes them into executable runtime contexts (sandboxes, containers, tool bindings) while maintaining full provenance and governance compliance.
CMS must not author semantics. It can only propose diffs.
This preserves the isomorphic principle where downstream layers can emit feedback, but the Semantic Core remains authoritative.
What the enterprise means/wants.
Conceptually aligned to SEA™’s Entity/Resource/Flow/Policy primitives.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"specId": "ContextSpec:v5-uuid",
"version": "1.2.0",
"concepts": ["Entity:User", "Entity:Transaction", "Resource:PaymentAPI"],
"policies": ["Policy:ComplianceCheck", "Policy:DataResidency"],
"capabilities": {
"tools": ["ToolSpec:Database", "ToolSpec:HTTPClient"],
"resources": {
"cpu": "2",
"memory": "4Gi"
}
},
"constraints": ["CALM:BoundedContext:Payments"]
}
What was actually built.
provisioning → ready → running → retired1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"instanceId": "ContextInstance:runtime-uuid",
"specRef": "ContextSpec:v5-uuid",
"status": "running",
"endpoints": {
"api": "http://localhost:8080",
"tools": ["http://localhost:8081/db", "http://localhost:8082/http"]
},
"digests": {
"image": "sha256:abc123...",
"dataset": "sha256:def456..."
},
"provenanceRef": "Ledger:token-uuid",
"calmComplianceRef": "CALMReport:report-uuid"
}
What is true right now about the instance.
1
2
3
4
5
6
7
8
9
10
11
12
{
"snapshotId": "ContextSnapshot:snap-uuid",
"instanceRef": "ContextInstance:runtime-uuid",
"timestamp": "2025-12-21T10:30:00Z",
"health": "healthy",
"activeConnections": 5,
"resourceUsage": {
"cpu": "1.2",
"memory": "2.1Gi"
},
"capabilities": ["database:connected", "http:available"]
}
“Given ContextSpecRef, create a ContextInstance”
1
2
3
4
5
6
interface MaterializeContextPort {
materialize(
specRef: string,
parameters: MaterializeParams
): Promise<ContextInstance>;
}
Start/stop/pause/resume/terminate instance
1
2
3
4
5
6
7
interface LifecyclePort {
start(instanceId: string): Promise<void>;
stop(instanceId: string): Promise<void>;
pause(instanceId: string): Promise<void>;
resume(instanceId: string): Promise<void>;
terminate(instanceId: string): Promise<void>;
}
Get status, capabilities, logs, provenance receipts
1
2
3
4
5
6
interface IntrospectPort {
getStatus(instanceId: string): Promise<InstanceStatus>;
getCapabilities(instanceId: string): Promise<Capability[]>;
getLogs(instanceId: string, options: LogOptions): Promise<LogEntry[]>;
getProvenance(instanceId: string): Promise<ProvenanceReceipt>;
}
Resolve ConceptIds, validate semantic refs, fetch policies/rules.
Persist instance + edges (implements/provides/dependsOn), attach receipts.
Validate “this instance topology is allowed” + attach compliance report.
Mint IDs, store provenance attestations, link instance → spec → artifacts.
Docker / k8s / Firecracker / remote sandbox / etc.
Implication: Runtime is swappable without affecting semantics/governance.
POST /context/materialize
1
2
3
4
5
6
7
8
9
{
"contextSpecRef": "ContextSpec:v5-uuid",
"requestedBy": "user:alice",
"parameters": {
"region": "local",
"cpu": "2",
"memory": "4Gi"
}
}
Response:
1
2
3
4
5
{
"instanceId": "ContextInstance:runtime-uuid",
"status": "provisioning",
"estimatedReadyTime": "2025-12-21T10:35:00Z"
}
GET /context/instances/{instanceId}
POST /context/instances/{instanceId}/freeze
Produces an immutable “instance recipe” (digests only) for replay.
POST /context/instances/{instanceId}/terminate
GET /context/instances/{instanceId}/snapshot
Emitted when API called / pipeline starts.
1
2
3
4
5
6
{
"eventType": "ContextMaterializationRequested",
"specRef": "ContextSpec:v5-uuid",
"requestedBy": "user:alice",
"timestamp": "2025-12-21T10:30:00Z"
}
Emitted on successful materialization.
1
2
3
4
5
6
7
8
9
10
{
"eventType": "ContextMaterialized",
"contextSpecRef": "ContextSpec:v5-uuid",
"contextInstanceId": "ContextInstance:runtime-uuid",
"runtimeDigest": "sha256:abc123...",
"capabilities": ["database", "http"],
"provenanceRef": "Ledger:token-uuid",
"calmComplianceRef": "CALMReport:report-uuid",
"timestamp": "2025-12-21T10:35:00Z"
}
Emitted on failure with structured reasons.
1
2
3
4
5
6
7
8
9
{
"eventType": "ContextMaterializationFailed",
"specRef": "ContextSpec:v5-uuid",
"reasons": [
{ "code": "RESOURCE_UNAVAILABLE", "detail": "GPU quota exceeded" },
{ "code": "POLICY_VIOLATION", "detail": "DataResidency constraint failed" }
],
"timestamp": "2025-12-21T10:32:00Z"
}
Canonical feed for agents + Context Analyzer consumers.
Produced when CALM/SBVR constraints fail for spec→instance mapping.
Produced if runtime topology diverges from declaration.
Note: Drift detection is not optional; ADR-001 treats it as a deployment gate.
CMS writes instance facts as nodes/edges:
ContextSpec materialized_as ContextInstanceContextInstance depends_on Resource (datasets, images, tool adapters)ContextInstance provides Capability (tool endpoints, API surfaces)ContextInstance complies_with Policy (SBVR/CALM control IDs)It cannot redefine “User” or “Transaction.” It can only emit feedback suggesting changes.
Everything materialized must be addressable by digest (images, datasets, tool versions). Otherwise, context replay is theater.
Cannot just validate spec; must attach evidence that runtime complied (reports + receipts).
Clear separation between:
⏳ Post-MVP (advanced context execution)