@aiwg/cli 2026.9.0 → 2026.9.2

package/dist/src/dataset/ledger-types.d.ts

@@ -0,0 +1,141 @@
+import type { Digest, PrivacyClassification, ProcessingRun } from './types.js';
+export declare const RUN_LEDGER_VERSION: "aiwg.run-ledger/v1";
+export type RunLedgerVersion = typeof RUN_LEDGER_VERSION;
+export type ProvenanceBasis = 'declared' | 'observed' | 'imported' | 'inferred';
+export type PrincipalKind = 'person' | 'organization' | 'software' | 'service';
+export interface StructuredLocator {
+    scheme: 'file' | 'uri' | 'json-pointer' | 'line-column' | 'record-key' | 'external-id';
+    value: string;
+    field?: string;
+    line?: number;
+    column?: number;
+}
+export interface LedgerEntity {
+    recordType: 'entity';
+    id: string;
+    entityType: string;
+    revision?: string;
+    digest?: Digest;
+    privacy: PrivacyClassification;
+    retentionPolicy?: string;
+}
+export interface LedgerActivity {
+    recordType: 'activity';
+    id: string;
+    activityType: string;
+    runId?: string;
+    startedAt?: string;
+    endedAt?: string;
+    planDigest?: Digest;
+}
+export interface LedgerAgent {
+    recordType: 'agent';
+    id: string;
+    principalKind: PrincipalKind;
+    version?: string;
+}
+export interface LedgerEvidence {
+    recordType: 'evidence';
+    id: string;
+    source: StructuredLocator;
+    target?: StructuredLocator;
+    method: string;
+    confidence: number;
+    privacy: PrivacyClassification;
+    retentionPolicy?: string;
+    runId?: string;
+    responsibleAgentId: string;
+    observedAt: string;
+}
+export interface LedgerAssertion {
+    recordType: 'assertion';
+    id: string;
+    subjectId: string;
+    predicate: string;
+    objectId: string;
+    basis: ProvenanceBasis;
+    evidenceIds: string[];
+    activityId?: string;
+    runId?: string;
+    field?: string;
+    privacy: PrivacyClassification;
+    retentionPolicy?: string;
+}
+export interface LedgerCorrection {
+    recordType: 'correction';
+    id: string;
+    correctsEventId: string;
+    replacementEventId?: string;
+    reason: string;
+    responsibleAgentId: string;
+}
+export interface LedgerSupersession {
+    recordType: 'supersession';
+    id: string;
+    supersedesEventId: string;
+    successorEventId: string;
+    reason?: string;
+}
+export type LedgerRecord = LedgerEntity | LedgerActivity | LedgerAgent | LedgerEvidence | LedgerAssertion | LedgerCorrection | LedgerSupersession;
+export interface LedgerEvent {
+    schemaVersion: RunLedgerVersion;
+    eventId: string;
+    runId?: string;
+    sequence: number;
+    recordedAt: string;
+    producer: {
+        id: string;
+        version: string;
+    };
+    record: LedgerRecord;
+    eventDigest: Digest;
+}
+export interface RunLedgerSnapshot {
+    schemaVersion: RunLedgerVersion;
+    events: LedgerEvent[];
+}
+export interface ProjectionLossItem {
+    path: string;
+    reason: string;
+    severity: 'information' | 'semantic' | 'privacy';
+    sourcePrivacy?: PrivacyClassification;
+    retentionPolicy?: string;
+}
+export interface ProjectionLossReport {
+    profile: string;
+    lossless: boolean;
+    items: ProjectionLossItem[];
+}
+export interface ProjectionResult<T> {
+    value: T;
+    loss: ProjectionLossReport;
+}
+export interface W3cProvProjection {
+    entity: Record<string, Record<string, unknown>>;
+    activity: Record<string, Record<string, unknown>>;
+    agent: Record<string, Record<string, unknown>>;
+    wasDerivedFrom: Array<{
+        generatedEntity: string;
+        usedEntity: string;
+        evidence?: string[];
+    }>;
+    wasGeneratedBy: Array<{
+        entity: string;
+        activity: string;
+    }>;
+    used: Array<{
+        activity: string;
+        entity: string;
+        evidence?: string[];
+    }>;
+    wasAssociatedWith: Array<{
+        activity: string;
+        agent: string;
+    }>;
+    wasAttributedTo: Array<{
+        entity: string;
+        agent: string;
+    }>;
+}
+export type LedgerProcessingRun = ProcessingRun;
+//# sourceMappingURL=ledger-types.d.ts.map

package/dist/src/dataset/ledger-types.js

@@ -0,0 +1,2 @@
+export const RUN_LEDGER_VERSION = 'aiwg.run-ledger/v1';
+//# sourceMappingURL=ledger-types.js.map

package/dist/src/dataset/ledger.d.ts

@@ -0,0 +1,27 @@
+import { type LedgerEvent, type LedgerRecord, type RunLedgerSnapshot } from './ledger-types.js';
+export declare class RunLedgerError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function computeLedgerEventDigest(event: Omit<LedgerEvent, 'eventDigest'>): LedgerEvent['eventDigest'];
+export declare function createLedgerEvent(input: Omit<LedgerEvent, 'schemaVersion' | 'eventDigest'>): LedgerEvent;
+export declare function verifyLedgerEventDigest(event: LedgerEvent): boolean;
+export declare class RunLedger {
+    private readonly events;
+    private readonly eventIds;
+    private readonly recordIds;
+    append(event: LedgerEvent): {
+        appended: boolean;
+        event: LedgerEvent;
+    };
+    get(eventId: string): LedgerEvent | undefined;
+    snapshot(): RunLedgerSnapshot;
+    query(options?: {
+        runId?: string;
+        recordType?: LedgerRecord['recordType'];
+        afterSequence?: number;
+        limit?: number;
+    }): LedgerEvent[];
+    static replay(events: readonly LedgerEvent[]): RunLedger;
+}
+//# sourceMappingURL=ledger.d.ts.map

package/dist/src/dataset/ledger.js

@@ -0,0 +1,100 @@
+import { datasetDigest } from './contracts.js';
+import { RUN_LEDGER_VERSION } from './ledger-types.js';
+export class RunLedgerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'RunLedgerError';
+    }
+}
+export function computeLedgerEventDigest(event) { return datasetDigest(event); }
+export function createLedgerEvent(input) { const event = { schemaVersion: RUN_LEDGER_VERSION, ...input }; return { ...event, eventDigest: computeLedgerEventDigest(event) }; }
+export function verifyLedgerEventDigest(event) { const { eventDigest, ...content } = event; return eventDigest?.algorithm === 'sha256' && eventDigest.value === computeLedgerEventDigest(content).value; }
+function references(record) {
+    switch (record.recordType) {
+        case 'evidence': return [record.responsibleAgentId];
+        case 'assertion': return [record.subjectId, record.objectId, ...record.evidenceIds, ...(record.activityId ? [record.activityId] : [])];
+        case 'correction': return [record.correctsEventId, ...(record.replacementEventId ? [record.replacementEventId] : []), record.responsibleAgentId];
+        case 'supersession': return [record.supersedesEventId, record.successorEventId];
+        default: return [];
+    }
+}
+function validateRecord(record) {
+    const supported = new Set(['entity', 'activity', 'agent', 'evidence', 'assertion', 'correction', 'supersession']);
+    if (!record || typeof record !== 'object' || !supported.has(record.recordType))
+        throw new RunLedgerError('RUN_LEDGER_RECORD_TYPE_UNSUPPORTED', 'record type is not part of the governed run-ledger vocabulary');
+    if (record.recordType === 'assertion' && record.basis === 'observed') {
+        if (!record.runId)
+            throw new RunLedgerError('RUN_LEDGER_OBSERVED_RUN_REQUIRED', 'observed assertions require run identity');
+        if (record.evidenceIds.length === 0)
+            throw new RunLedgerError('RUN_LEDGER_OBSERVED_EVIDENCE_REQUIRED', 'observed assertions require evidence');
+    }
+    if (record.recordType === 'evidence') {
+        if (record.confidence < 0 || record.confidence > 1)
+            throw new RunLedgerError('RUN_LEDGER_CONFIDENCE_INVALID', 'evidence confidence must be from 0 through 1');
+        for (const locator of [record.source, record.target].filter((value) => value !== undefined)) {
+            if (locator.value.includes('\0') || locator.value.includes('\n') || locator.value.includes('\r'))
+                throw new RunLedgerError('RUN_LEDGER_LOCATOR_INVALID', 'evidence locator contains control characters');
+            if (locator.scheme === 'file' && (locator.value.startsWith('/') || locator.value.split(/[\\/]/u).includes('..')))
+                throw new RunLedgerError('RUN_LEDGER_LOCATOR_INVALID', 'file evidence locator must be repository-relative without traversal');
+            if (locator.scheme === 'uri') {
+                try {
+                    new URL(locator.value);
+                }
+                catch {
+                    throw new RunLedgerError('RUN_LEDGER_LOCATOR_INVALID', 'URI evidence locator is malformed');
+                }
+            }
+        }
+    }
+}
+export class RunLedger {
+    events = [];
+    eventIds = new Map();
+    recordIds = new Map();
+    append(event) {
+        if (event.schemaVersion !== RUN_LEDGER_VERSION)
+            throw new RunLedgerError('RUN_LEDGER_VERSION_UNSUPPORTED', `unsupported ledger version ${event.schemaVersion}`);
+        validateRecord(event.record);
+        const globallyScoped = /^[A-Za-z][A-Za-z0-9+.-]*:.+$/u;
+        if (!globallyScoped.test(event.eventId))
+            throw new RunLedgerError('RUN_LEDGER_EVENT_ID_INVALID', `event ID ${event.eventId} must be globally scoped`);
+        const runIds = [event.runId, 'runId' in event.record ? event.record.runId : undefined].filter((value) => value !== undefined);
+        if (runIds.some((runId) => !globallyScoped.test(runId)))
+            throw new RunLedgerError('RUN_LEDGER_RUN_ID_INVALID', 'run IDs must be globally scoped');
+        if (!verifyLedgerEventDigest(event))
+            throw new RunLedgerError('RUN_LEDGER_DIGEST_MISMATCH', `event ${event.eventId} digest does not match immutable content`);
+        const existing = this.eventIds.get(event.eventId);
+        if (existing) {
+            if (existing.eventDigest.value === event.eventDigest.value)
+                return { appended: false, event: existing };
+            throw new RunLedgerError('RUN_LEDGER_EVENT_ID_CONFLICT', `event ID ${event.eventId} was reused with different content`);
+        }
+        if (event.sequence !== this.events.length + 1)
+            throw new RunLedgerError('RUN_LEDGER_SEQUENCE_INVALID', `expected sequence ${this.events.length + 1}; received ${event.sequence}`);
+        if (this.recordIds.has(event.record.id))
+            throw new RunLedgerError('RUN_LEDGER_RECORD_ID_CONFLICT', `record ID ${event.record.id} is immutable and already exists`);
+        const known = new Set([...this.eventIds.keys(), ...this.recordIds.keys()]);
+        const missing = references(event.record).filter((id) => !known.has(id));
+        if (missing.length)
+            throw new RunLedgerError('RUN_LEDGER_REFERENCE_DANGLING', `event ${event.eventId} has dangling references: ${missing.sort().join(', ')}`);
+        this.events.push(event);
+        this.eventIds.set(event.eventId, event);
+        this.recordIds.set(event.record.id, event);
+        return { appended: true, event };
+    }
+    get(eventId) { return this.eventIds.get(eventId); }
+    snapshot() { return { schemaVersion: RUN_LEDGER_VERSION, events: [...this.events] }; }
+    query(options = {}) {
+        const limit = options.limit ?? 100;
+        if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
+            throw new RunLedgerError('RUN_LEDGER_QUERY_LIMIT_INVALID', 'limit must be from 1 through 1000');
+        if (options.afterSequence !== undefined && (!Number.isInteger(options.afterSequence) || options.afterSequence < 0))
+            throw new RunLedgerError('RUN_LEDGER_QUERY_CURSOR_INVALID', 'afterSequence must be a non-negative integer');
+        return this.events.filter((event) => (options.runId === undefined || event.runId === options.runId) && (options.recordType === undefined || event.record.recordType === options.recordType) && (options.afterSequence === undefined || event.sequence > options.afterSequence)).slice(0, limit);
+    }
+    static replay(events) { const ledger = new RunLedger(); for (const event of events)
+        ledger.append(event); return ledger; }
+}
+//# sourceMappingURL=ledger.js.map

package/dist/src/dataset/local-execution-backend.d.ts

@@ -0,0 +1,10 @@
+import type { DatasetExecutionBackend, ExecutionRequest, ExecutionResult } from "./orchestration-types.js";
+export declare class LocalDatasetExecutionBackend implements DatasetExecutionBackend {
+    readonly id = "local";
+    capabilities(): {
+        name: string;
+        version: string;
+    }[];
+    execute(r: ExecutionRequest): Promise<ExecutionResult>;
+}
+//# sourceMappingURL=local-execution-backend.d.ts.map

package/dist/src/dataset/local-execution-backend.js

@@ -0,0 +1,32 @@
+export class LocalDatasetExecutionBackend {
+    id = "local";
+    capabilities() {
+        return [
+            { name: "incremental-read", version: "1" },
+            { name: "materialize-records", version: "1" },
+        ];
+    }
+    async execute(r) {
+        if (r.signal?.aborted)
+            return {
+                outcome: "cancelled",
+                attemptedRecords: 0,
+                committedRecords: 0,
+                rejectedRecords: 0,
+                diagnostics: [],
+            };
+        return {
+            outcome: "committed",
+            attemptedRecords: r.records.length,
+            committedRecords: r.records.length,
+            rejectedRecords: 0,
+            diagnostics: [],
+            artifact: {
+                id: `artifact:${r.plan.id}`,
+                revisionId: r.plan.planDigest.value,
+                records: r.records,
+            },
+        };
+    }
+}
+//# sourceMappingURL=local-execution-backend.js.map

package/dist/src/dataset/orchestration-repository.d.ts

@@ -0,0 +1,29 @@
+import type { ProcessingPlan } from "./types.js";
+import type { DatasetRunState, RegisteredSource } from "./orchestration-types.js";
+export interface DatasetOrchestrationRepository {
+    getSource(id: string): Promise<RegisteredSource | undefined>;
+    putSource(source: RegisteredSource): Promise<void>;
+    getPlan(id: string): Promise<ProcessingPlan | undefined>;
+    putPlan(plan: ProcessingPlan): Promise<void>;
+    getRun(id: string): Promise<DatasetRunState | undefined>;
+    getRunByIdempotency(key: string): Promise<DatasetRunState | undefined>;
+    putRun(run: DatasetRunState): Promise<void>;
+    listArtifactRecords(id: string): Promise<readonly unknown[]>;
+    putArtifactRecords(id: string, records: readonly unknown[]): Promise<void>;
+}
+export declare class MemoryDatasetOrchestrationRepository implements DatasetOrchestrationRepository {
+    sources: Map<string, RegisteredSource>;
+    plans: Map<string, ProcessingPlan>;
+    runs: Map<string, DatasetRunState>;
+    artifacts: Map<string, readonly unknown[]>;
+    getSource(id: string): Promise<RegisteredSource | undefined>;
+    putSource(v: RegisteredSource): Promise<void>;
+    getPlan(id: string): Promise<ProcessingPlan | undefined>;
+    putPlan(v: ProcessingPlan): Promise<void>;
+    getRun(id: string): Promise<DatasetRunState | undefined>;
+    getRunByIdempotency(key: string): Promise<DatasetRunState | undefined>;
+    putRun(v: DatasetRunState): Promise<void>;
+    listArtifactRecords(id: string): Promise<readonly unknown[]>;
+    putArtifactRecords(id: string, v: readonly unknown[]): Promise<void>;
+}
+//# sourceMappingURL=orchestration-repository.d.ts.map

package/dist/src/dataset/orchestration-repository.js

@@ -0,0 +1,34 @@
+export class MemoryDatasetOrchestrationRepository {
+    sources = new Map();
+    plans = new Map();
+    runs = new Map();
+    artifacts = new Map();
+    async getSource(id) {
+        return this.sources.get(id);
+    }
+    async putSource(v) {
+        this.sources.set(v.id, structuredClone(v));
+    }
+    async getPlan(id) {
+        return this.plans.get(id);
+    }
+    async putPlan(v) {
+        this.plans.set(v.id, structuredClone(v));
+    }
+    async getRun(id) {
+        return this.runs.get(id);
+    }
+    async getRunByIdempotency(key) {
+        return [...this.runs.values()].find((v) => v.idempotencyKey === key);
+    }
+    async putRun(v) {
+        this.runs.set(v.runId, structuredClone(v));
+    }
+    async listArtifactRecords(id) {
+        return this.artifacts.get(id) ?? [];
+    }
+    async putArtifactRecords(id, v) {
+        this.artifacts.set(id, structuredClone(v));
+    }
+}
+//# sourceMappingURL=orchestration-repository.js.map

package/dist/src/dataset/orchestration-service.d.ts

@@ -0,0 +1,56 @@
+import type { DatasetOrchestrationRepository } from "./orchestration-repository.js";
+import { type CapabilityProfile, type ProcessingPlan } from "./types.js";
+import { type DatasetOrchestrationDependencies, type DatasetResult, type RegisteredSource } from "./orchestration-types.js";
+export declare class DatasetOrchestrationError extends Error {
+    readonly code: string;
+    readonly boundary: DatasetResult["diagnostics"][number]["boundary"];
+    readonly retryable: boolean;
+    constructor(code: string, message: string, boundary?: DatasetResult["diagnostics"][number]["boundary"], retryable?: boolean);
+}
+export declare class DatasetOrchestrationService {
+    private readonly repo;
+    private readonly deps;
+    constructor(repo: DatasetOrchestrationRepository, deps: DatasetOrchestrationDependencies);
+    private now;
+    private offlineRemote;
+    source(source: RegisteredSource): Promise<DatasetResult<unknown>>;
+    private context;
+    check(id: string, offline?: boolean): Promise<DatasetResult<unknown>>;
+    preview(id: string, count?: number, offline?: boolean, signal?: AbortSignal): Promise<DatasetResult<unknown>>;
+    plan(input: {
+        id: string;
+        sourceId: string;
+        profile: CapabilityProfile;
+        schemas: ProcessingPlan["schemas"];
+        policy: ProcessingPlan["policy"];
+        backend?: "local" | "fortemi-core";
+        fallback?: "local";
+        estimates?: ProcessingPlan["estimates"];
+        approvals?: ProcessingPlan["approvals"];
+        reconciliation?: ProcessingPlan["reconciliation"];
+        steps: ProcessingPlan["steps"];
+        artifactClasses: ProcessingPlan["artifactClasses"];
+        createdBy: string;
+        offline?: boolean;
+    }): Promise<DatasetResult<unknown>>;
+    ingest(input: {
+        planId: string;
+        planDigest: string;
+        idempotencyKey: string;
+        approvalIds?: string[];
+        reconciliationApproval?: {
+            previewDigest: string;
+            threshold: number;
+        };
+        signal?: AbortSignal;
+    }): Promise<DatasetResult<unknown>>;
+    status(runId: string): Promise<DatasetResult<unknown>>;
+    show(id: string): Promise<DatasetResult<unknown>>;
+    verify(runId: string): Promise<DatasetResult<unknown>>;
+    query(artifactId: string): Promise<DatasetResult<unknown>>;
+    lineage(runId: string): Promise<DatasetResult<unknown>>;
+    export(artifactId: string): Promise<DatasetResult<unknown>>;
+    cancel(runId: string): Promise<DatasetResult<unknown>>;
+    retry(runId: string, signal?: AbortSignal): Promise<DatasetResult<unknown>>;
+}
+//# sourceMappingURL=orchestration-service.d.ts.map