@ddse/acm-sdk 0.5.0

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Core types for ACM v0.5
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,0BAA0B"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@ddse/acm-sdk",
+  "version": "0.5.0",
+  "description": "ACM v0.5 SDK - Abstract classes and types",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "keywords": [
+    "acm",
+    "sdk",
+    "types"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node ./dist/tests/phase4-integration.test.js",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch"
+  }
+}

package/src/capability.ts

@@ -0,0 +1,11 @@
+// Abstract CapabilityRegistry class
+import type { Capability } from './types.js';
+import type { Task } from './task.js';
+
+export abstract class CapabilityRegistry {
+  abstract list(): Capability[];
+  abstract has(name: string): boolean;
+  abstract resolve(name: string): Task<any, any> | undefined;
+  abstract inputSchema(name: string): unknown | undefined;
+  abstract outputSchema(name: string): unknown | undefined;
+}

package/src/context-provider.ts

@@ -0,0 +1,136 @@
+import type { Nucleus } from './nucleus.js';
+import type { RunContext, InternalContextScope } from './types.js';
+import type { Tool } from './tool.js';
+
+export type ContextRetrievalArtifact = {
+  type: string;
+  content: any;
+  promote?: boolean;
+  provenance?: {
+    tool?: string;
+    rationale?: string;
+    [key: string]: any;
+  };
+};
+
+export type ContextRetrievalResult =
+  | ContextRetrievalArtifact
+  | ContextRetrievalArtifact[]
+  | null
+  | undefined;
+
+export type ContextRetrievalTool = Tool<any, ContextRetrievalResult>;
+
+export type ContextRetrievalBindingOptions = {
+  match?: (directive: string) => boolean;
+  buildInput?: (
+    directive: string,
+    context: {
+      runContext?: RunContext;
+      nucleus?: Nucleus;
+    }
+  ) => any;
+  autoPromote?: boolean;
+  maxArtifacts?: number;
+  describe?: string;
+};
+
+type Binding = {
+  tool: ContextRetrievalTool;
+  match: (directive: string) => boolean;
+  buildInput: (
+    directive: string,
+    context: {
+      runContext?: RunContext;
+      nucleus?: Nucleus;
+    }
+  ) => any;
+  autoPromote: boolean;
+  maxArtifacts: number;
+  describe?: string;
+};
+
+export class ExternalContextProviderAdapter {
+  private bindings: Binding[] = [];
+
+  register(tool: ContextRetrievalTool, options?: ContextRetrievalBindingOptions): void {
+    const match: Binding['match'] =
+      options?.match ??
+      ((directive: string) =>
+        directive.startsWith(`${tool.name()}:`) || directive.startsWith(`${tool.name()}::`));
+
+    const buildInput: Binding['buildInput'] =
+      options?.buildInput ?? ((directive: string) => {
+        const separatorIndex = directive.indexOf(':');
+        const payload = separatorIndex >= 0 ? directive.slice(separatorIndex + 1) : undefined;
+        return {
+          directive,
+          payload,
+        };
+      });
+
+    this.bindings.push({
+      tool,
+      match,
+      buildInput,
+      autoPromote: options?.autoPromote ?? true,
+      maxArtifacts: options?.maxArtifacts ?? 16,
+      describe: options?.describe,
+    });
+  }
+
+  async fulfill(request: {
+    directives: string[];
+    scope: InternalContextScope;
+    runContext?: RunContext;
+    nucleus?: Nucleus;
+  }): Promise<void> {
+    const { directives, scope, runContext, nucleus } = request;
+
+    const unresolved: string[] = [];
+
+    for (const directive of directives) {
+      const binding = this.bindings.find(entry => entry.match(directive));
+      if (!binding) {
+        unresolved.push(directive);
+        continue;
+      }
+
+      const input = binding.buildInput(directive, { runContext, nucleus });
+      const result = await binding.tool.call(input);
+      if (!result) {
+        continue;
+      }
+
+      const artifacts = Array.isArray(result) ? result : [result];
+      if (artifacts.length > binding.maxArtifacts) {
+        throw new Error(
+          `Tool ${binding.tool.name()} returned ${artifacts.length} artifacts for directive ${directive}, exceeding limit ${binding.maxArtifacts}`
+        );
+      }
+
+      for (const artifact of artifacts) {
+        if (!artifact || typeof artifact.type !== 'string') {
+          throw new Error(
+            `Tool ${binding.tool.name()} returned an invalid artifact for directive ${directive}`
+          );
+        }
+
+        const provenance = artifact.provenance ?? {
+          tool: binding.tool.name(),
+        };
+
+        const artifactId = scope.addArtifact(artifact.type, artifact.content, provenance);
+        if (artifact.promote ?? binding.autoPromote) {
+          await scope.promote(artifactId);
+        }
+      }
+    }
+
+    if (unresolved.length > 0) {
+      throw new Error(
+        `No context retrieval tool registered for directives: ${unresolved.join(', ')}`
+      );
+    }
+  }
+}

package/src/context.ts

@@ -0,0 +1,190 @@
+// Context orchestration utilities
+
+import { createHash } from 'crypto';
+import type { ContextPacket, InternalContextScope, LedgerEntry } from './types.js';
+
+export class ContextBuilder {
+  private sources: ContextPacket['sources'] = [];
+  private facts: Record<string, any> = {};
+  private assumptions: string[] = [];
+  private augmentations: ContextPacket['augmentations'] = [];
+  private provenance: ContextPacket['provenance'] = {};
+
+  addSource(uri: string, type?: string, content?: any): this {
+    const digest = this.computeDigest(content ? JSON.stringify(content) : uri);
+    this.sources!.push({ uri, digest, type });
+    return this;
+  }
+
+  addFact(key: string, value: any): this {
+    this.facts[key] = value;
+    return this;
+  }
+
+  addFacts(facts: Record<string, any>): this {
+    Object.assign(this.facts, facts);
+    return this;
+  }
+
+  addAssumption(assumption: string): this {
+    this.assumptions.push(assumption);
+    return this;
+  }
+
+  addAugmentation(type: string, artifact: string): this {
+    this.augmentations!.push({ type, artifact });
+    return this;
+  }
+
+  setProvenance(provenance: ContextPacket['provenance']): this {
+    this.provenance = provenance;
+    return this;
+  }
+
+  build(version?: string): ContextPacket {
+    const packet: ContextPacket = {
+      id: this.computePacketId(),
+      version,
+      sources: this.sources,
+      facts: this.facts,
+      assumptions: this.assumptions.length > 0 ? this.assumptions : undefined,
+      augmentations: this.augmentations,
+      provenance: this.provenance,
+    };
+
+    return packet;
+  }
+
+  private computePacketId(): string {
+    // Compute SHA-256 hash of the normalized packet
+    const normalized = JSON.stringify({
+      sources: this.sources,
+      facts: this.facts,
+      assumptions: this.assumptions,
+      augmentations: this.augmentations,
+    });
+    const hash = createHash('sha256');
+    hash.update(normalized);
+    return `sha256-${hash.digest('hex')}`;
+  }
+
+  private computeDigest(content: string): string {
+    const hash = createHash('sha256');
+    hash.update(content);
+    return `sha256-${hash.digest('hex').substring(0, 32)}`;
+  }
+
+  static computeContextRef(context: ContextPacket): string {
+    // Compute full SHA-256 hash of the normalized context packet
+    const normalized = JSON.stringify({
+      sources: context.sources,
+      facts: context.facts,
+      assumptions: context.assumptions,
+      augmentations: context.augmentations,
+    });
+    const hash = createHash('sha256');
+    hash.update(normalized);
+    return hash.digest('hex');
+  }
+}
+
+export class InternalContextScopeImpl implements InternalContextScope {
+  artifacts: Array<{
+    id: string;
+    type: string;
+    content: any;
+    digest: string;
+    provenance?: {
+      retrievedAt: number;
+      tool?: string;
+      rationale?: string;
+    };
+  }> = [];
+
+  private ledgerAppend?: (entry: LedgerEntry) => void;
+  private contextBuilder?: ContextBuilder;
+
+  constructor(ledgerAppend?: (entry: LedgerEntry) => void) {
+    this.ledgerAppend = ledgerAppend;
+  }
+
+  addArtifact(
+    type: string,
+    content: any,
+    provenance?: {
+      tool?: string;
+      rationale?: string;
+    }
+  ): string {
+    const id = `artifact-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+    const digest = this.computeDigest(JSON.stringify(content));
+
+    this.artifacts.push({
+      id,
+      type,
+      content,
+      digest,
+      provenance: provenance
+        ? {
+            retrievedAt: Date.now(),
+            ...provenance,
+          }
+        : undefined,
+    });
+
+    // Record to ledger
+    if (this.ledgerAppend) {
+      this.ledgerAppend({
+        id: `context-internal-${Date.now()}-${Math.random().toString(36).substring(7)}`,
+        ts: Date.now(),
+        type: 'CONTEXT_INTERNALIZED',
+        details: {
+          artifactId: id,
+          type,
+          digest,
+          provenance,
+        },
+      });
+    }
+
+    return id;
+  }
+
+  async promote(artifactId: string): Promise<void> {
+    const artifact = this.artifacts.find(a => a.id === artifactId);
+    if (!artifact) {
+      throw new Error(`Artifact not found: ${artifactId}`);
+    }
+
+    // In a real implementation, this would create a new Context Packet version
+    // and append to the context builder
+    if (this.contextBuilder) {
+      this.contextBuilder.addAugmentation(artifact.type, artifact.id);
+    }
+
+    // Log promotion
+    if (this.ledgerAppend) {
+      this.ledgerAppend({
+        id: `context-promote-${Date.now()}-${Math.random().toString(36).substring(7)}`,
+        ts: Date.now(),
+        type: 'CONTEXT_INTERNALIZED',
+        details: {
+          action: 'promote',
+          artifactId,
+          digest: artifact.digest,
+        },
+      });
+    }
+  }
+
+  getArtifact(id: string): any {
+    const artifact = this.artifacts.find(a => a.id === id);
+    return artifact?.content;
+  }
+
+  private computeDigest(content: string): string {
+    const hash = createHash('sha256');
+    hash.update(content);
+    return hash.digest('hex').substring(0, 32);
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+// SDK exports
+export * from './types.js';
+export * from './tool.js';
+export * from './task.js';
+export * from './capability.js';
+export * from './registry.js';
+export * from './policy.js';
+export * from './stream.js';
+export * from './nucleus.js';
+export * from './context.js';
+export * from './context-provider.js';
+export * from './utils.js';