@haaaiawd/second-nature 0.1.1 → 0.1.3

package/runtime/storage/repositories/provenance-repository.js

@@ -0,0 +1,41 @@
+import { eq } from "drizzle-orm";
+import { provenanceEdges } from "../db/schema/index.js";
+export class ProvenanceRepository {
+    database;
+    constructor(database) {
+        this.database = database;
+    }
+    async create(record) {
+        await this.database.db.insert(provenanceEdges).values(record);
+    }
+    async listByTarget(toId) {
+        return this.database.db.select().from(provenanceEdges).where(eq(provenanceEdges.toId, toId));
+    }
+    async linkEntrySources(entryId, sourceRefs) {
+        for (const sourceId of sourceRefs) {
+            await this.create({
+                id: `prov:${Date.now()}:${Math.random().toString(36).slice(2, 8)}`,
+                fromId: sourceId,
+                toId: entryId,
+                kind: "source",
+                createdAt: new Date().toISOString(),
+            });
+        }
+    }
+    async traceAsset(assetId) {
+        const edges = await this.listByTarget(assetId);
+        const upstreamSources = edges.filter((e) => e.kind === "source").map((e) => e.fromId);
+        const proposalIds = edges.filter((e) => e.kind === "proposal").map((e) => e.fromId);
+        const applyIds = edges.filter((e) => e.kind === "apply").map((e) => e.fromId);
+        return { assetId, upstreamSources, proposalIds, applyIds };
+    }
+    async recordApply(proposalId, assetId, info) {
+        await this.create({
+            id: `apply:${Date.now()}:${Math.random().toString(36).slice(2, 8)}`,
+            fromId: proposalId,
+            toId: assetId,
+            kind: "apply",
+            createdAt: new Date().toISOString(),
+        });
+    }
+}

package/runtime/storage/services/credential-vault.d.ts

@@ -0,0 +1,8 @@
+import type { StateDatabase } from "../db/index.js";
+import type { CredentialContextWrite, CredentialContext, CredentialState } from "../../shared/types/index.js";
+export interface CredentialVault {
+    saveCredentialContext(input: CredentialContextWrite): Promise<void>;
+    loadCredentialContext(platformId: string): Promise<CredentialContext | null>;
+    getCredentialState(platformId: string): Promise<CredentialState>;
+}
+export declare function createCredentialVault(db: StateDatabase["db"]): CredentialVault;

package/runtime/storage/services/credential-vault.js

@@ -0,0 +1,78 @@
+import * as crypto from "crypto";
+import { eq } from "drizzle-orm";
+import { credentialRecords } from "../db/schema/index.js";
+const ENCRYPTION_KEY = process.env.SECOND_NATURE_ENCRYPTION_KEY || crypto.randomBytes(32).toString("hex");
+const ALGORITHM = "aes-256-gcm";
+function encrypt(plaintext) {
+    const iv = crypto.randomBytes(16);
+    const key = Buffer.from(ENCRYPTION_KEY.slice(0, 32), "utf8");
+    const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return iv.toString("hex") + ":" + authTag.toString("hex") + ":" + encrypted.toString("hex");
+}
+function decrypt(ciphertext) {
+    const parts = ciphertext.split(":");
+    if (parts.length !== 3)
+        return ciphertext;
+    const iv = Buffer.from(parts[0], "hex");
+    const authTag = Buffer.from(parts[1], "hex");
+    const encrypted = Buffer.from(parts[2], "hex");
+    const key = Buffer.from(ENCRYPTION_KEY.slice(0, 32), "utf8");
+    const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+    decipher.setAuthTag(authTag);
+    return decipher.update(encrypted) + decipher.final("utf8");
+}
+export function createCredentialVault(db) {
+    return {
+        async saveCredentialContext(input) {
+            const encrypted = input.encryptedValue ? encrypt(input.encryptedValue) : "";
+            await db.insert(credentialRecords).values({
+                platformId: input.platformId,
+                credentialType: input.credentialType,
+                encryptedValue: encrypted,
+                status: input.status,
+                verificationCode: input.verificationCode ?? null,
+                challengeText: input.challengeText ?? null,
+                expiresAt: input.expiresAt ?? null,
+                attemptsRemaining: input.attemptsRemaining ?? null,
+                updatedAt: new Date().toISOString(),
+            }).onConflictDoUpdate({
+                target: credentialRecords.platformId,
+                set: {
+                    credentialType: input.credentialType,
+                    encryptedValue: encrypted,
+                    status: input.status,
+                    verificationCode: input.verificationCode ?? null,
+                    challengeText: input.challengeText ?? null,
+                    expiresAt: input.expiresAt ?? null,
+                    attemptsRemaining: input.attemptsRemaining ?? null,
+                    updatedAt: new Date().toISOString(),
+                },
+            });
+        },
+        async loadCredentialContext(platformId) {
+            const record = await db.query.credentialRecords.findFirst({
+                where: (tbl) => eq(tbl.platformId, platformId),
+            });
+            if (!record)
+                return null;
+            return {
+                platformId: record.platformId,
+                credentialType: record.credentialType,
+                status: record.status,
+                encryptedValue: record.encryptedValue ? decrypt(record.encryptedValue) : undefined,
+                verificationCode: record.verificationCode ?? undefined,
+                challengeText: record.challengeText ?? undefined,
+                verificationDeadline: record.expiresAt ?? undefined,
+                attemptsRemaining: record.attemptsRemaining ?? undefined,
+            };
+        },
+        async getCredentialState(platformId) {
+            const record = await db.query.credentialRecords.findFirst({
+                where: (tbl) => eq(tbl.platformId, platformId),
+            });
+            return record?.status || "missing";
+        },
+    };
+}

package/runtime/storage/services/daily-log-pipeline.d.ts

@@ -0,0 +1,47 @@
+import type { AssetRepository } from "../repositories/asset-repository.js";
+import type { ProvenanceRepository } from "../repositories/provenance-repository.js";
+export interface ActivityLogWrite {
+    id: string;
+    timestamp: string;
+    platform?: string;
+    kind: "browse" | "action" | "failure" | "task" | "heartbeat";
+    content: string;
+    sourceRefs: string[];
+}
+export interface ObservationWrite {
+    id: string;
+    timestamp: string;
+    summary: string;
+    mood?: string;
+    sourceRefs: string[];
+}
+export interface DailyReportInput {
+    day: string;
+    summary: string;
+    highlights: string[];
+    activityRefs: string[];
+    observationRefs: string[];
+}
+export interface CuratedMemoryWrite {
+    id: string;
+    title: string;
+    summary: string;
+    confidence: number;
+    ttlClass: "short" | "medium" | "long";
+    sourceRefs: string[];
+    supersedes?: string[];
+}
+export interface AssetWriteAck {
+    assetPath: string;
+    hash: string;
+}
+export declare class DailyLogPipeline {
+    private readonly assetRepository;
+    private readonly provenanceRepository;
+    constructor(assetRepository: AssetRepository, provenanceRepository: ProvenanceRepository);
+    appendActivityLog(entry: ActivityLogWrite): Promise<AssetWriteAck>;
+    appendObservation(entry: ObservationWrite): Promise<AssetWriteAck>;
+    generateDailyReport(input: DailyReportInput): Promise<AssetWriteAck>;
+    upsertCuratedMemory(candidate: CuratedMemoryWrite): Promise<AssetWriteAck>;
+}
+export declare function createDailyLogPipeline(assetRepository: AssetRepository, provenanceRepository: ProvenanceRepository): DailyLogPipeline;

package/runtime/storage/services/daily-log-pipeline.js

@@ -0,0 +1,86 @@
+import { writeCanonicalArtifact, appendLine, hashFile, resolveDailyJournalPath, resolveDailyReportPath, resolveCuratedPath, serializeActivityLog, serializeObservation, renderDailyReport, renderCuratedMemory, buildJournalAssetId, buildReportAssetId, buildCuratedAssetId, } from "../memory/workspace/paths.js";
+export class DailyLogPipeline {
+    assetRepository;
+    provenanceRepository;
+    constructor(assetRepository, provenanceRepository) {
+        this.assetRepository = assetRepository;
+        this.provenanceRepository = provenanceRepository;
+    }
+    async appendActivityLog(entry) {
+        const journalPath = resolveDailyJournalPath(entry.timestamp);
+        const serialized = serializeActivityLog(entry);
+        await appendLine(journalPath, serialized);
+        const hash = await hashFile(journalPath);
+        await this.assetRepository.upsert({
+            id: buildJournalAssetId(journalPath),
+            kind: "daily_journal",
+            path: journalPath,
+            hash,
+            version: 1,
+            layer: "daily_journal",
+            lastIndexedAt: new Date().toISOString(),
+        });
+        if (entry.sourceRefs.length > 0) {
+            await this.provenanceRepository.linkEntrySources(entry.id, entry.sourceRefs);
+        }
+        return { assetPath: journalPath, hash };
+    }
+    async appendObservation(entry) {
+        const journalPath = resolveDailyJournalPath(entry.timestamp);
+        const serialized = serializeObservation(entry);
+        await appendLine(journalPath, serialized);
+        const hash = await hashFile(journalPath);
+        await this.assetRepository.upsert({
+            id: buildJournalAssetId(journalPath),
+            kind: "daily_journal",
+            path: journalPath,
+            hash,
+            version: 1,
+            layer: "daily_journal",
+            lastIndexedAt: new Date().toISOString(),
+        });
+        return { assetPath: journalPath, hash };
+    }
+    async generateDailyReport(input) {
+        const reportPath = resolveDailyReportPath(input.day);
+        const content = renderDailyReport(input);
+        await writeCanonicalArtifact(reportPath, content);
+        const hash = await hashFile(reportPath);
+        await this.assetRepository.upsert({
+            id: buildReportAssetId(input.day),
+            kind: "daily_report",
+            path: reportPath,
+            hash,
+            version: 1,
+            layer: "daily_journal",
+            lastIndexedAt: new Date().toISOString(),
+        });
+        await this.provenanceRepository.linkEntrySources(buildReportAssetId(input.day), [
+            ...input.activityRefs,
+            ...input.observationRefs,
+        ]);
+        return { assetPath: reportPath, hash };
+    }
+    async upsertCuratedMemory(candidate) {
+        const curatedPath = resolveCuratedPath(candidate.id);
+        const content = renderCuratedMemory(candidate);
+        await writeCanonicalArtifact(curatedPath, content);
+        const hash = await hashFile(curatedPath);
+        await this.assetRepository.upsert({
+            id: buildCuratedAssetId(candidate.id),
+            kind: "curated_memory",
+            path: curatedPath,
+            hash,
+            version: 1,
+            layer: "curated_memory",
+            lastIndexedAt: new Date().toISOString(),
+        });
+        if (candidate.sourceRefs.length > 0) {
+            await this.provenanceRepository.linkEntrySources(buildCuratedAssetId(candidate.id), candidate.sourceRefs);
+        }
+        return { assetPath: curatedPath, hash };
+    }
+}
+export function createDailyLogPipeline(assetRepository, provenanceRepository) {
+    return new DailyLogPipeline(assetRepository, provenanceRepository);
+}

package/runtime/storage/services/effect-commit-store.d.ts

@@ -0,0 +1,11 @@
+import type { StateDatabase } from "../db/index.js";
+import type { IntentCommitRecord, IntentCommitRecordInput, IntentCommitState, IntentCommitOutcome } from "../../shared/types/index.js";
+export interface EffectCommitStore {
+    createIntentCommitRecord(input: IntentCommitRecordInput): Promise<IntentCommitRecord>;
+    advanceIntentCommitState(id: string, state: IntentCommitState, metadata?: Record<string, unknown>): Promise<void>;
+    commitIntentOutcome(id: string, outcome: IntentCommitOutcome): Promise<void>;
+    loadIntentCommitRecord(intentId: string): Promise<IntentCommitRecord | null>;
+    abortIntentCommit(id: string, reason: string): Promise<void>;
+    markIntentCommitReconcile(id: string, details: Record<string, unknown>): Promise<void>;
+}
+export declare function createEffectCommitStore(db: StateDatabase["db"]): EffectCommitStore;

package/runtime/storage/services/effect-commit-store.js

@@ -0,0 +1,93 @@
+import * as crypto from "crypto";
+import { eq } from "drizzle-orm";
+import { intentCommitRecords } from "../db/schema/index.js";
+const VALID_TRANSITIONS = {
+    planned: ["dispatched", "aborted"],
+    dispatched: ["externally_acknowledged", "aborted"],
+    externally_acknowledged: ["committed", "reconcile", "aborted"],
+    committed: [],
+    reconcile: ["planned", "aborted"],
+    aborted: [],
+};
+export function createEffectCommitStore(db) {
+    return {
+        async createIntentCommitRecord(input) {
+            const record = {
+                id: crypto.randomUUID(),
+                intentId: input.intentId,
+                decisionId: input.decisionId,
+                checkpointId: input.checkpointId ?? null,
+                state: input.state,
+                outcomeRef: null,
+                metadataJson: null,
+                updatedAt: new Date().toISOString(),
+            };
+            await db.insert(intentCommitRecords).values(record);
+            return {
+                id: record.id,
+                intentId: record.intentId,
+                decisionId: record.decisionId,
+                checkpointId: record.checkpointId ?? undefined,
+                state: record.state,
+                outcomeRef: undefined,
+                metadata: undefined,
+                updatedAt: record.updatedAt,
+            };
+        },
+        async advanceIntentCommitState(id, state, metadata) {
+            const existing = await db.query.intentCommitRecords.findFirst({
+                where: (tbl) => eq(tbl.id, id),
+            });
+            if (!existing)
+                throw new Error("intent_commit_not_found");
+            const currentState = existing.state;
+            const allowed = VALID_TRANSITIONS[currentState] ?? [];
+            if (!allowed.includes(state)) {
+                throw new Error(`invalid_state_transition: ${currentState} -> ${state}`);
+            }
+            await db.update(intentCommitRecords).set({
+                state,
+                metadataJson: metadata ? JSON.stringify(metadata) : null,
+                updatedAt: new Date().toISOString(),
+            }).where(eq(intentCommitRecords.id, id));
+        },
+        async commitIntentOutcome(id, outcome) {
+            await db.update(intentCommitRecords).set({
+                state: "committed",
+                outcomeRef: outcome.outcomeRef,
+                metadataJson: JSON.stringify({ traceId: outcome.traceId }),
+                updatedAt: new Date().toISOString(),
+            }).where(eq(intentCommitRecords.id, id));
+        },
+        async loadIntentCommitRecord(intentId) {
+            const record = await db.query.intentCommitRecords.findFirst({
+                where: (tbl) => eq(tbl.intentId, intentId),
+            });
+            if (!record)
+                return null;
+            return {
+                id: record.id,
+                intentId: record.intentId,
+                decisionId: record.decisionId,
+                checkpointId: record.checkpointId ?? undefined,
+                state: record.state,
+                outcomeRef: record.outcomeRef ?? undefined,
+                metadata: record.metadataJson ? JSON.parse(record.metadataJson) : undefined,
+                updatedAt: record.updatedAt,
+            };
+        },
+        async abortIntentCommit(id, _reason) {
+            await db.update(intentCommitRecords).set({
+                state: "aborted",
+                updatedAt: new Date().toISOString(),
+            }).where(eq(intentCommitRecords.id, id));
+        },
+        async markIntentCommitReconcile(id, details) {
+            await db.update(intentCommitRecords).set({
+                state: "reconcile",
+                metadataJson: JSON.stringify(details),
+                updatedAt: new Date().toISOString(),
+            }).where(eq(intentCommitRecords.id, id));
+        },
+    };
+}

package/runtime/storage/services/governance-layer.d.ts

@@ -0,0 +1,40 @@
+import type { StateDatabase } from "../db/index.js";
+import { ProposalRepository } from "../repositories/proposal-repository.js";
+import { AssetRepository } from "../repositories/asset-repository.js";
+import { ProvenanceRepository } from "../repositories/provenance-repository.js";
+export interface AnchorWriteProposal {
+    id: string;
+    targetAssetId: string;
+    beforeHash?: string;
+    afterHash?: string;
+    status: "draft" | "requires_review" | "approved" | "rejected" | "applied" | "conflicted";
+    proposedDiff: string;
+    reason: string;
+    supportingSources: string[];
+    confidence: number;
+    policyBasis?: string[];
+    riskFlags?: string[];
+    createdAt: string;
+}
+export interface ProposalAck {
+    proposalId: string;
+    proposalPath: string;
+    status: string;
+}
+export interface ApplyAck {
+    applied: boolean;
+    assetId: string;
+    hash: string;
+}
+export declare class GovernanceLayer {
+    private readonly proposalRepository;
+    private readonly assetRepository;
+    private readonly provenanceRepository;
+    constructor(proposalRepository: ProposalRepository, assetRepository: AssetRepository, provenanceRepository: ProvenanceRepository);
+    proposeAnchorWrite(proposal: AnchorWriteProposal): Promise<ProposalAck>;
+    applyGovernedAnchorWrite(proposalId: string): Promise<ApplyAck>;
+    approveProposal(proposalId: string): Promise<void>;
+    rejectProposal(proposalId: string): Promise<void>;
+    loadProposal(proposalId: string): Promise<AnchorWriteProposal | null>;
+}
+export declare function createGovernanceLayer(database: StateDatabase): GovernanceLayer;

package/runtime/storage/services/governance-layer.js

@@ -0,0 +1,103 @@
+import { ProposalRepository } from "../repositories/proposal-repository.js";
+import { AssetRepository } from "../repositories/asset-repository.js";
+import { ProvenanceRepository } from "../repositories/provenance-repository.js";
+import { writeCanonicalArtifact, readText, hashFile, resolveProposalPath, renderProposal, applyDiff, } from "../memory/workspace/paths.js";
+const CONFIDENCE_THRESHOLD_FOR_ANCHOR = 0.8;
+export class GovernanceLayer {
+    proposalRepository;
+    assetRepository;
+    provenanceRepository;
+    constructor(proposalRepository, assetRepository, provenanceRepository) {
+        this.proposalRepository = proposalRepository;
+        this.assetRepository = assetRepository;
+        this.provenanceRepository = provenanceRepository;
+    }
+    async proposeAnchorWrite(proposal) {
+        if (!proposal.supportingSources.length) {
+            throw new Error("anchor_proposal_requires_sources");
+        }
+        if (proposal.confidence < CONFIDENCE_THRESHOLD_FOR_ANCHOR) {
+            throw new Error("anchor_proposal_confidence_too_low");
+        }
+        const proposalPath = resolveProposalPath(proposal.id);
+        const initialStatus = (proposal.riskFlags && proposal.riskFlags.length > 0) ? "requires_review" : "draft";
+        await writeCanonicalArtifact(proposalPath, renderProposal(proposal));
+        await this.proposalRepository.create({
+            id: proposal.id,
+            targetAssetId: proposal.targetAssetId,
+            beforeHash: proposal.beforeHash ?? null,
+            afterHash: proposal.afterHash ?? null,
+            status: initialStatus,
+            proposedDiff: proposal.proposedDiff,
+            reason: proposal.reason,
+            supportingSources: JSON.stringify(proposal.supportingSources),
+            confidence: proposal.confidence,
+            createdAt: proposal.createdAt ?? new Date().toISOString(),
+        });
+        if (proposal.supportingSources.length > 0) {
+            await this.provenanceRepository.linkEntrySources(proposal.id, proposal.supportingSources);
+        }
+        return { proposalId: proposal.id, proposalPath, status: initialStatus };
+    }
+    async applyGovernedAnchorWrite(proposalId) {
+        const proposal = await this.proposalRepository.findById(proposalId);
+        if (!proposal) {
+            throw new Error("proposal_not_found");
+        }
+        if (proposal.status !== "approved") {
+            throw new Error("proposal_not_approved");
+        }
+        const target = await this.assetRepository.findById(proposal.targetAssetId);
+        if (!target) {
+            throw new Error("target_asset_not_found");
+        }
+        const beforeContent = await readText(target.path);
+        const beforeHash = await hashFile(target.path);
+        if (proposal.beforeHash && proposal.beforeHash !== beforeHash) {
+            await this.proposalRepository.updateStatus(proposalId, "conflicted");
+            throw new Error("anchor_proposal_conflict");
+        }
+        const nextContent = applyDiff(beforeContent, proposal.proposedDiff);
+        await writeCanonicalArtifact(target.path, nextContent);
+        const hash = await hashFile(target.path);
+        await this.assetRepository.upsert({
+            ...target,
+            hash,
+            version: target.version + 1,
+            lastIndexedAt: new Date().toISOString(),
+        });
+        await this.proposalRepository.updateStatus(proposalId, "applied", hash);
+        await this.provenanceRepository.recordApply(proposalId, target.id, {
+            beforeHash,
+            afterHash: hash,
+            diff: proposal.proposedDiff,
+        });
+        return { applied: true, assetId: target.id, hash };
+    }
+    async approveProposal(proposalId) {
+        await this.proposalRepository.updateStatus(proposalId, "approved");
+    }
+    async rejectProposal(proposalId) {
+        await this.proposalRepository.updateStatus(proposalId, "rejected");
+    }
+    async loadProposal(proposalId) {
+        const record = await this.proposalRepository.findById(proposalId);
+        if (!record)
+            return null;
+        return {
+            id: record.id,
+            targetAssetId: record.targetAssetId,
+            beforeHash: record.beforeHash ?? undefined,
+            afterHash: record.afterHash ?? undefined,
+            status: record.status,
+            proposedDiff: record.proposedDiff,
+            reason: record.reason,
+            supportingSources: JSON.parse(record.supportingSources),
+            confidence: record.confidence,
+            createdAt: record.createdAt,
+        };
+    }
+}
+export function createGovernanceLayer(database) {
+    return new GovernanceLayer(new ProposalRepository(database), new AssetRepository(database), new ProvenanceRepository(database));
+}

package/runtime/storage/services/persona-candidate-loader.d.ts

@@ -0,0 +1,5 @@
+import type { PersonaCandidate, SceneContext } from "../../guidance/types.js";
+export interface PersonaCandidateLoader {
+    loadPersonaCandidates(sceneContext: SceneContext): Promise<PersonaCandidate[]>;
+}
+export declare function createPersonaCandidateLoader(): PersonaCandidateLoader;

package/runtime/storage/services/persona-candidate-loader.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+import { readText, resolveAnchorPath } from "../memory/workspace/paths.js";
+const ANCHOR_ASSET_SOURCES = [
+    { source: "SOUL", fileName: "SOUL.md" },
+    { source: "USER", fileName: "USER.md" },
+    { source: "IDENTITY", fileName: "IDENTITY.md" },
+    { source: "MEMORY", fileName: "MEMORY.md" },
+];
+function toTags(sceneContext, fileName) {
+    const base = path.basename(fileName, ".md").toLowerCase();
+    return [sceneContext.sceneType, sceneContext.mode, base];
+}
+function toSnippetCandidates(input) {
+    const normalized = input.content
+        .split(/\r?\n{2,}/)
+        .map((chunk) => chunk.replace(/^#+\s+/gm, "").replace(/\s+/g, " ").trim())
+        .filter((chunk) => chunk.length > 0)
+        .slice(0, 6);
+    return normalized.map((text, index) => ({
+        id: `${input.source.toLowerCase()}-${index + 1}`,
+        source: input.source,
+        text,
+        tags: toTags(input.sceneContext, input.fileName),
+    }));
+}
+export function createPersonaCandidateLoader() {
+    return {
+        async loadPersonaCandidates(sceneContext) {
+            const loaded = await Promise.all(ANCHOR_ASSET_SOURCES.map(async ({ source, fileName }) => {
+                const content = await readText(resolveAnchorPath(fileName));
+                return toSnippetCandidates({
+                    sceneContext,
+                    source,
+                    fileName,
+                    content,
+                });
+            }));
+            return loaded.flat();
+        },
+    };
+}

package/runtime/storage/services/provenance-service.d.ts

@@ -0,0 +1,40 @@
+import type { StateDatabase } from "../db/index.js";
+import { ProvenanceRepository } from "../repositories/provenance-repository.js";
+import { ProposalRepository } from "../repositories/proposal-repository.js";
+import { AssetRepository } from "../repositories/asset-repository.js";
+export interface ProvenanceTrace {
+    assetId: string;
+    upstreamSources: string[];
+    proposalIds: string[];
+    applyIds: string[];
+}
+export interface ProvenanceDetail {
+    assetId: string;
+    assetPath?: string;
+    assetHash?: string;
+    assetVersion?: number;
+    currentContent?: string;
+    provenance: ProvenanceTrace;
+    proposals?: Array<{
+        id: string;
+        status: string;
+        targetAssetId: string;
+        proposedDiff: string;
+        reason: string;
+        confidence: number;
+        supportingSources: string[];
+    }>;
+    applies?: Array<{
+        id: string;
+        beforeHash: string;
+        afterHash: string;
+    }>;
+}
+export declare class ProvenanceService {
+    private readonly provenanceRepository;
+    private readonly proposalRepository;
+    private readonly assetRepository;
+    constructor(provenanceRepository: ProvenanceRepository, proposalRepository: ProposalRepository, assetRepository: AssetRepository);
+    explainProvenance(assetId: string): Promise<ProvenanceDetail>;
+}
+export declare function createProvenanceService(database: StateDatabase): ProvenanceService;

package/runtime/storage/services/provenance-service.js

@@ -0,0 +1,43 @@
+import { ProvenanceRepository } from "../repositories/provenance-repository.js";
+import { ProposalRepository } from "../repositories/proposal-repository.js";
+import { AssetRepository } from "../repositories/asset-repository.js";
+export class ProvenanceService {
+    provenanceRepository;
+    proposalRepository;
+    assetRepository;
+    constructor(provenanceRepository, proposalRepository, assetRepository) {
+        this.provenanceRepository = provenanceRepository;
+        this.proposalRepository = proposalRepository;
+        this.assetRepository = assetRepository;
+    }
+    async explainProvenance(assetId) {
+        const asset = await this.assetRepository.findById(assetId);
+        const trace = await this.provenanceRepository.traceAsset(assetId);
+        const proposals = [];
+        for (const pid of trace.proposalIds) {
+            const p = await this.proposalRepository.findById(pid);
+            if (p) {
+                proposals.push({
+                    id: p.id,
+                    status: p.status,
+                    targetAssetId: p.targetAssetId,
+                    proposedDiff: p.proposedDiff,
+                    reason: p.reason,
+                    confidence: p.confidence,
+                    supportingSources: JSON.parse(p.supportingSources),
+                });
+            }
+        }
+        return {
+            assetId,
+            assetPath: asset?.path,
+            assetHash: asset?.hash,
+            assetVersion: asset?.version,
+            provenance: trace,
+            proposals,
+        };
+    }
+}
+export function createProvenanceService(database) {
+    return new ProvenanceService(new ProvenanceRepository(database), new ProposalRepository(database), new AssetRepository(database));
+}