@popmelt.com/core 0.8.4 → 0.8.6

package/dist/memory-store.d.mts

@@ -0,0 +1,1048 @@
+declare const MEMORY_FORMAT_VERSION: 1;
+declare const MEMORY_SCHEMA_VERSION: 1;
+type MemoryFormatVersion = typeof MEMORY_FORMAT_VERSION;
+type MemorySchemaVersion = typeof MEMORY_SCHEMA_VERSION;
+type MemoryId = string;
+type Timestamp = string;
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type SourceReferenceKind = 'thread' | 'message' | 'iteration' | 'artifact' | 'event' | 'record' | 'external';
+type SourceReference = {
+    kind: SourceReferenceKind;
+    id: string;
+    uri?: string;
+    excerpt?: string;
+};
+type Provenance = {
+    id: MemoryId;
+    schemaVersion: MemorySchemaVersion;
+    projectId: MemoryId;
+    createdAt: Timestamp;
+    participantId: MemoryId;
+    sourceRefs: SourceReference[];
+};
+type ParticipantKind = 'human' | 'ai' | 'system' | 'integration';
+type AuthorityLevel = 'owner' | 'delegate' | 'contributor';
+type AuthorityMode = 'local_trusted' | 'hosted';
+type ExecutionContext = {
+    sessionId?: string;
+    provider?: string;
+    model?: string;
+    deviceId?: string;
+    mode?: string;
+};
+type AuthorityContext = {
+    level: AuthorityLevel;
+    mode: AuthorityMode;
+    grantId?: MemoryId;
+    authenticatedAt?: Timestamp;
+};
+type ParticipantRecord = Provenance & {
+    recordType: 'participant';
+    kind: ParticipantKind;
+    displayName: string;
+    status: 'active' | 'disabled';
+};
+type AuthorityGrantRecord = Provenance & {
+    recordType: 'authority_grant';
+    granteeId: MemoryId;
+    level: AuthorityLevel;
+    grantedById: MemoryId;
+    subjectIds: MemoryId[];
+    startsAt: Timestamp;
+    endsAt?: Timestamp;
+    revokedAt?: Timestamp;
+};
+type SubjectType = 'project' | 'file' | 'route' | 'component' | 'element' | 'token' | 'interaction';
+type SubjectLocatorKind = 'project_root' | 'source_file' | 'route_pattern' | 'file_export' | 'source_span' | 'dom_selector' | 'token_path' | 'interaction_key' | 'custom';
+type SubjectLocator = {
+    id: MemoryId;
+    kind: SubjectLocatorKind;
+    value: string;
+    status: 'current' | 'historical' | 'unresolved';
+    validFrom: Timestamp;
+    validUntil?: Timestamp;
+    sourceRefs: SourceReference[];
+};
+type SubjectRecord = Provenance & {
+    recordType: 'subject';
+    subjectType: SubjectType;
+    label: string;
+    aliases: string[];
+    locators: SubjectLocator[];
+};
+type ParticipantStance = {
+    stance: 'supports' | 'opposes' | 'uncertain' | 'needs_evidence';
+    reason?: string;
+};
+type CaptureContext = {
+    route?: string;
+    subjectIds: MemoryId[];
+    artifactIds: MemoryId[];
+};
+type ObservationState = 'open' | 'resolved' | 'dismissed';
+type ObservationRecord = Provenance & {
+    recordType: 'observation';
+    state: ObservationState;
+    statement: string;
+    captureContext: CaptureContext;
+    stance?: ParticipantStance;
+    resolvedByIds: MemoryId[];
+};
+type DecisionKind = 'principle' | 'preference' | 'rule' | 'constraint';
+type ProposalState = 'draft' | 'pending' | 'accepted' | 'rejected' | 'withdrawn' | 'deferred';
+type AssertionOrigin = {
+    mode: 'declared' | 'inferred';
+    sourceText?: string;
+    iterationId?: MemoryId;
+    inferredById?: MemoryId;
+    reviewedById?: MemoryId;
+};
+type DecisionSubject = {
+    subjectId: MemoryId;
+    role: 'governed' | 'consumer' | 'provider' | 'context';
+};
+type ProposalRecord = Provenance & {
+    recordType: 'proposal';
+    state: ProposalState;
+    claim: string;
+    rationale?: string;
+    proposedKind?: DecisionKind;
+    subjects: DecisionSubject[];
+    subjectSemantics?: string;
+    origin: AssertionOrigin;
+    stance?: ParticipantStance;
+    bundleId?: MemoryId;
+};
+type DecisionState = 'active' | 'superseded' | 'revoked';
+type DecisionRecord = Provenance & {
+    recordType: 'decision';
+    proposalId: MemoryId;
+    acceptanceEventId: MemoryId;
+    acceptedById: MemoryId;
+    authority: AuthorityContext;
+    state: DecisionState;
+    kind: DecisionKind;
+    claim: string;
+    rationale?: string;
+    subjects: DecisionSubject[];
+    subjectSemantics?: string;
+    noChange: boolean;
+    effectiveAt?: Timestamp;
+    effectiveMilestone?: string;
+    bundleId?: MemoryId;
+};
+type ThreadOutcome = 'decision_created' | 'proposal_rejected' | 'observation_resolved' | 'observation_dismissed' | 'question_unresolved' | 'implementation_only' | 'no_outcome';
+type ThreadRecord = Provenance & {
+    recordType: 'thread';
+    title?: string;
+    state: 'open' | 'resolved';
+    messageArtifactIds: MemoryId[];
+    outcome: ThreadOutcome;
+    resultRefs: EntityReference[];
+};
+type IterationOutcome = 'completed' | 'cancelled' | 'question_asked' | 'failed' | 'no_change';
+type IterationRecord = Provenance & {
+    recordType: 'iteration';
+    threadIds: MemoryId[];
+    startedAt: Timestamp;
+    completedAt?: Timestamp;
+    requestSummary: string;
+    responseSummary?: string;
+    outcome: IterationOutcome;
+    execution: ExecutionContext;
+    artifactIds: MemoryId[];
+};
+type EvidenceKind = 'judgment' | 'artifact' | 'eval' | 'log' | 'user_feedback' | 'external_source' | 'project_state';
+type EvidenceRecord = Provenance & {
+    recordType: 'evidence';
+    kind: EvidenceKind;
+    summary: string;
+    availability: 'available' | 'missing' | 'redacted' | 'forgotten';
+    stance?: ParticipantStance;
+    artifactIds: MemoryId[];
+};
+type CoverageClaim = {
+    decisionId: MemoryId;
+    coverage: 'partial' | 'full';
+    claim: string;
+    sourceRefs: SourceReference[];
+};
+type ImplementationState = 'planned' | 'in_progress' | 'completed' | 'failed' | 'abandoned';
+type ImplementationAttemptRecord = Provenance & {
+    recordType: 'implementation_attempt';
+    state: ImplementationState;
+    iterationIds: MemoryId[];
+    coverageClaims: CoverageClaim[];
+    projectStateRef?: SourceReference;
+    summary: string;
+    artifactIds: MemoryId[];
+};
+type VerificationState = 'queued' | 'running' | 'passed' | 'failed' | 'inconclusive' | 'error' | 'cancelled';
+type VerificationTarget = {
+    entityType: 'decision' | 'implementation_attempt' | 'model_entry';
+    entityId: MemoryId;
+};
+type EvalSpecState = 'draft' | 'active' | 'retired';
+type EvalDependency = {
+    kind: 'model_path' | 'source_file' | 'route' | 'subject';
+    value: string;
+    subjectId?: MemoryId;
+};
+type EvalScenario = {
+    id: string;
+    label?: string;
+    route?: string;
+    routePattern?: string;
+    components?: Array<{
+        name: string;
+        sourceFile?: string;
+        exportName?: string;
+    }>;
+    subjectIds?: MemoryId[];
+    states?: Array<{
+        kind: 'viewport' | 'theme' | 'auth' | 'locale' | 'feature_flag' | 'fixture' | 'interaction' | 'custom';
+        key?: string;
+        value: string;
+    }>;
+    steps?: Array<{
+        action: 'navigate' | 'click' | 'type' | 'select';
+        target?: string;
+        value?: string;
+    }>;
+};
+type EvalSpecRecord = Provenance & {
+    recordType: 'eval_spec';
+    state: EvalSpecState;
+    legacyId: string;
+    replacesSpecId?: MemoryId;
+    title: string;
+    category: 'component' | 'layout' | 'copy' | 'interaction' | 'visual' | 'workflow';
+    prompt: string;
+    assertions: string[];
+    rationale: string;
+    decisionIds: MemoryId[];
+    subjectIds: MemoryId[];
+    threadRefs: string[];
+    dependencies?: EvalDependency[];
+    scenarios?: EvalScenario[];
+    targets: VerificationTarget[];
+    evaluator: {
+        kind: 'human' | 'ai' | 'test' | 'external';
+        name: string;
+        evidenceTypes: string[];
+    };
+    scope: {
+        kind: 'current_page' | 'project' | 'subject';
+        route?: string;
+    };
+};
+type VerificationAttemptRecord = Provenance & {
+    recordType: 'verification_attempt';
+    evalSpecId?: MemoryId;
+    scopeFingerprint?: string;
+    state: VerificationState;
+    evaluator: {
+        kind: 'human' | 'ai' | 'test' | 'eval' | 'external';
+        participantId?: MemoryId;
+        name: string;
+    };
+    targets: VerificationTarget[];
+    summary?: string;
+    evidenceIds: MemoryId[];
+    /** Compact presentation data for an eval run; raw output remains an artifact/thread detail. */
+    evalRun?: {
+        id: string;
+        threadId?: string;
+        createdAt: number;
+        completedAt: number;
+        durationMs: number;
+        scope: {
+            type: 'current_page';
+            url: string;
+            viewport: {
+                width: number;
+                height: number;
+            };
+        };
+        assertionResults: Array<{
+            assertion: string;
+            status: 'pass' | 'fail' | 'needs_review';
+            summary: string;
+            evidence: string[];
+        }>;
+        tooling: {
+            chromeDevtools: 'available' | 'unavailable' | 'unknown';
+            evidenceTypes: string[];
+        };
+        provider?: string;
+        model?: string;
+        screenshotPath?: string;
+        codeFingerprint?: string;
+    };
+};
+type ModelEntryRecord = Provenance & {
+    recordType: 'model_entry';
+    key: string;
+    subjectIds: MemoryId[];
+    decisionIds: MemoryId[];
+    value: JsonValue;
+};
+type ModelProjectionRecord = Provenance & {
+    recordType: 'model_projection';
+    state: 'applied';
+    runId: string;
+    presentationJobId?: string;
+    appliedById: MemoryId;
+    authority: AuthorityContext;
+    appliedAt: Timestamp;
+    decisionIds: MemoryId[];
+    entryIds: MemoryId[];
+    coverage: Array<{
+        decisionId: MemoryId;
+        status: 'unprojected' | 'partially_projected' | 'projected' | 'stale';
+    }>;
+};
+type EntityType = 'participant' | 'authority_grant' | 'subject' | 'observation' | 'proposal' | 'decision' | 'thread' | 'iteration' | 'evidence' | 'implementation_attempt' | 'eval_spec' | 'verification_attempt' | 'model_entry' | 'model_projection' | 'freshness_signal';
+type MemoryObjectType = EntityType | 'relationship' | 'lifecycle_event' | 'artifact';
+type EntityReference = {
+    entityType: EntityType;
+    entityId: MemoryId;
+};
+type RelationshipType = 'supports' | 'contradicts' | 'supersedes' | 'excepts' | 'duplicates' | 'implements' | 'verifies' | 'replaces' | 'derived_from';
+type RelationshipRecord = Provenance & {
+    recordType: 'relationship';
+    relationshipType: RelationshipType;
+    from: EntityReference;
+    to: EntityReference;
+    reason: string;
+    authority?: AuthorityContext;
+};
+type FreshnessSignalType = 'subject_unresolved' | 'implementation_drift' | 'evidence_unavailable' | 'new_conflict' | 'verification_expired' | 'review_interval_elapsed' | 'schema_or_tooling_change';
+type FreshnessTargetKind = 'subject_locator' | 'implementation_presence' | 'verification_result' | 'model_coverage' | 'evidence_reference' | 'decision_applicability';
+type FreshnessSignalRecord = Provenance & {
+    recordType: 'freshness_signal';
+    signalType: FreshnessSignalType;
+    state: 'open' | 'resolved';
+    targetKind: FreshnessTargetKind;
+    target: EntityReference;
+    reason: string;
+    evidenceIds: MemoryId[];
+    resolvedAt?: Timestamp;
+    resolvedByEventId?: MemoryId;
+};
+type ProposalDeferralContext = {
+    kind: 'proposal_deferral';
+    taskContext?: string;
+    subjectIds: MemoryId[];
+    resurfaceWhen: Array<'different_action' | 'new_evidence' | 'new_conflict' | 'owner_request' | 'after_date'>;
+    revisitAfter?: Timestamp;
+};
+type LifecycleEvent = Provenance & {
+    recordType: 'lifecycle_event';
+    entity: EntityReference;
+    eventType: string;
+    fromState: string | null;
+    toState: string;
+    authority: AuthorityContext;
+    execution?: ExecutionContext;
+    reason?: string;
+    transitionContext?: ProposalDeferralContext;
+};
+type ArtifactKind = 'message' | 'screenshot' | 'image' | 'diff' | 'file_snapshot' | 'log' | 'eval_output' | 'external_document' | 'other';
+type ArtifactManifestEntry = {
+    id: MemoryId;
+    kind: ArtifactKind;
+    mediaType?: string;
+    byteSize?: number;
+    contentHash?: string;
+    location?: string;
+    availability: 'available' | 'missing' | 'redacted' | 'forgotten';
+};
+type Tombstone = {
+    id: MemoryId;
+    schemaVersion: MemorySchemaVersion;
+    projectId: MemoryId;
+    objectId: MemoryId;
+    objectType: MemoryObjectType;
+    deletedAt: Timestamp;
+    deletedById: MemoryId;
+    authority: AuthorityContext;
+    reasonCategory: 'privacy' | 'legal' | 'serious_error' | 'intentional_forgetting';
+    erasureLevel: 'content' | 'content_and_evidence' | 'full_where_permitted';
+    invalidates: EntityReference[];
+};
+type CanonicalRecord = ParticipantRecord | AuthorityGrantRecord | SubjectRecord | ObservationRecord | ProposalRecord | DecisionRecord | ThreadRecord | IterationRecord | EvidenceRecord | ImplementationAttemptRecord | EvalSpecRecord | VerificationAttemptRecord | ModelEntryRecord | ModelProjectionRecord | FreshnessSignalRecord;
+type MemoryFeature = 'authority' | 'subjects' | 'decisions' | 'implementations' | 'verification' | 'eval_specs' | 'model_projection' | 'freshness' | 'portable_artifacts' | 'bounded_retrieval';
+type ProjectMemoryManifest = {
+    formatVersion: MemoryFormatVersion;
+    projectId: MemoryId;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+    features: MemoryFeature[];
+    writer: {
+        name: string;
+        version: string;
+    };
+};
+type ProjectMemoryBundle = {
+    manifest: ProjectMemoryManifest;
+    records: CanonicalRecord[];
+    events: LifecycleEvent[];
+    relationships: RelationshipRecord[];
+    artifacts: ArtifactManifestEntry[];
+    tombstones: Tombstone[];
+};
+type SubjectMatch = {
+    subjectId?: MemoryId;
+    subjectType?: SubjectType;
+    label?: string;
+    confidence: 'exact' | 'strong' | 'weak' | 'unresolved';
+    matchedBy: 'id' | 'locator' | 'alias' | 'semantic' | 'none';
+    reason?: string;
+};
+type RetrievalDecision = {
+    id: MemoryId;
+    kind: DecisionKind;
+    claim: string;
+    subjectIds: MemoryId[];
+    authority: AuthorityContext;
+    effectiveState: 'active' | 'excepted' | 'conflicted';
+    freshness: FreshnessSignalType[];
+    expansionRef: SourceReference;
+};
+type RetrievalConflict = {
+    id: string;
+    decisionIds: MemoryId[];
+    unresolvedQuestion: string;
+    expansionRefs: SourceReference[];
+};
+type RetrievalUncertainty = {
+    code: 'subject_unresolved' | 'no_applicable_decision' | 'evidence_unavailable' | 'known_conflict' | 'retrieval_truncated';
+    message: string;
+    expansionRefs: SourceReference[];
+};
+type RetrievalEvidenceSummary = {
+    evidenceId: MemoryId;
+    summary: string;
+    availability: EvidenceRecord['availability'];
+    sourceRefs: SourceReference[];
+};
+type RetrievalPacket = {
+    contractVersion: 1;
+    projectId: MemoryId;
+    retrievedAt: Timestamp;
+    query: {
+        text?: string;
+        action?: string;
+        subjectHints: string[];
+    };
+    budget: {
+        maxEstimatedTokens: number;
+        estimatedTokens: number;
+    };
+    subjectMatches: SubjectMatch[];
+    modelEntries: Array<{
+        id: MemoryId;
+        key: string;
+        value: JsonValue;
+        decisionIds: MemoryId[];
+    }>;
+    evalSpecs: Array<{
+        id: MemoryId;
+        legacyId: string;
+        state: EvalSpecState;
+        title: string;
+        assertionCount: number;
+        decisionIds: MemoryId[];
+        expansionRef: SourceReference;
+    }>;
+    decisions: RetrievalDecision[];
+    conflicts: RetrievalConflict[];
+    uncertainties: RetrievalUncertainty[];
+    implementation: Array<{
+        decisionId: MemoryId;
+        state: 'unimplemented' | 'partial' | 'implemented' | 'unknown';
+        attemptIds: MemoryId[];
+    }>;
+    verification: Array<{
+        target: VerificationTarget;
+        state: 'unverified' | 'passing' | 'failing' | 'stale' | 'blocked';
+        attemptIds: MemoryId[];
+    }>;
+    evidence: RetrievalEvidenceSummary[];
+    completeness: {
+        status: 'complete' | 'truncated';
+        omittedDecisionCount: number;
+        omittedEvidenceCount: number;
+        conflictsComplete: boolean;
+    };
+};
+
+type SchemaIssue = {
+    path: string;
+    code: string;
+    message: string;
+    severity: 'error' | 'warning';
+};
+
+type ReviewCommandBase = {
+    proposalId: MemoryId;
+    participantId: MemoryId;
+    authority: AuthorityContext;
+    occurredAt: Timestamp;
+    sourceRefs?: SourceReference[];
+};
+type AcceptReviewCommand = ReviewCommandBase & {
+    action: 'accept';
+    eventId: MemoryId;
+    decisionId: MemoryId;
+    kind: DecisionKind;
+    rationale?: string;
+    reason: string;
+};
+type EditAndAcceptReviewCommand = ReviewCommandBase & {
+    action: 'edit_and_accept';
+    withdrawalEventId: MemoryId;
+    replacementProposalId: MemoryId;
+    acceptanceEventId: MemoryId;
+    decisionId: MemoryId;
+    relationshipId: MemoryId;
+    claim: string;
+    kind: DecisionKind;
+    subjects: DecisionSubject[];
+    subjectSemantics?: string;
+    rationale?: string;
+    reason: string;
+};
+type RejectReviewCommand = ReviewCommandBase & {
+    action: 'reject';
+    eventId: MemoryId;
+    reason: string;
+};
+type DeferReviewCommand = ReviewCommandBase & {
+    action: 'defer';
+    eventId: MemoryId;
+    reason?: string;
+    context: Omit<ProposalDeferralContext, 'kind'>;
+};
+type OwnerReviewCommand = AcceptReviewCommand | EditAndAcceptReviewCommand | RejectReviewCommand | DeferReviewCommand;
+type ReviewProjectionUpdate = {
+    entityType: 'proposal';
+    entityId: MemoryId;
+    fromState: ProposalRecord['state'];
+    state: ProposalRecord['state'];
+} | {
+    entityType: 'decision';
+    entityId: MemoryId;
+    fromState: DecisionRecord['state'];
+    state: DecisionRecord['state'];
+};
+type OwnerReviewActionPlan = {
+    action: OwnerReviewCommand['action'];
+    proposalId: MemoryId;
+    append: {
+        records: CanonicalRecord[];
+        events: LifecycleEvent[];
+        relationships: RelationshipRecord[];
+    };
+    projectionUpdates: ReviewProjectionUpdate[];
+    resultRefs: Array<{
+        entityType: 'proposal' | 'decision';
+        entityId: MemoryId;
+    }>;
+};
+type OwnerReviewPlanResult = {
+    ok: true;
+    plan: OwnerReviewActionPlan;
+} | {
+    ok: false;
+    errors: Array<{
+        code: string;
+        message: string;
+    }>;
+};
+
+type MemoryJournalMutation = {
+    records: CanonicalRecord[];
+    events: LifecycleEvent[];
+    relationships: RelationshipRecord[];
+    artifacts: ArtifactManifestEntry[];
+    tombstones: Tombstone[];
+    projectionUpdates: ReviewProjectionUpdate[];
+};
+type MemoryJournalTransaction = {
+    storageVersion: 1;
+    sequence: number;
+    transactionId: string;
+    projectId: string;
+    committedAt: string;
+    previousHash: string | null;
+    mutation: MemoryJournalMutation;
+    hash: string;
+};
+type MemoryJournalManifest = {
+    storageVersion: 1;
+    projectId: string;
+    checkpoint: {
+        file: string;
+        sequence: number;
+        hash: string;
+    };
+    head: {
+        sequence: number;
+        hash: string | null;
+    };
+    updatedAt: string;
+};
+type MemoryJournalLoadReport = {
+    checkpointSequence: number;
+    appliedTransactions: number;
+    recoveredTransactions: number;
+    ignoredTemporaryFiles: number;
+    headSequence: number;
+    headHash: string | null;
+};
+type MemoryJournalLoadResult = {
+    bundle: ProjectMemoryBundle;
+    report: MemoryJournalLoadReport;
+};
+type CommitReviewPlanOptions = {
+    transactionId: string;
+    committedAt: string;
+};
+declare function computeTransactionHash(transaction: Omit<MemoryJournalTransaction, 'hash'>): string;
+declare class MemoryJournalStore {
+    private readonly memoryDir;
+    private readonly journalDir;
+    private readonly manifestPath;
+    private readonly checkpointPath;
+    private readonly lockPath;
+    private writeChain;
+    constructor(projectRoot: string);
+    initialize(bundle: ProjectMemoryBundle): Promise<void>;
+    load(): Promise<MemoryJournalLoadResult>;
+    recover(): Promise<MemoryJournalLoadResult>;
+    rotateCheckpoint(): Promise<MemoryJournalLoadResult>;
+    maintain(checkpointInterval?: number): Promise<MemoryJournalLoadResult>;
+    commit(mutation: MemoryJournalMutation, options: CommitReviewPlanOptions): Promise<MemoryJournalLoadResult>;
+    commitReviewPlan(plan: OwnerReviewActionPlan, options: CommitReviewPlanOptions): Promise<MemoryJournalLoadResult>;
+    private loadInternal;
+    private enqueueWrite;
+    private withWriterLock;
+}
+
+type ContextualReviewQuery = {
+    action?: string;
+    text?: string;
+    subjectIds?: MemoryId[];
+    subjectHints?: string[];
+    maxPackets?: number;
+    maxEstimatedTokens?: number;
+    generatedAt?: Timestamp;
+    candidateProposalIds?: MemoryId[];
+    candidateDecisionIds?: MemoryId[];
+    resurface?: {
+        differentAction?: boolean;
+        newEvidence?: boolean;
+        newConflict?: boolean;
+        ownerRequested?: boolean;
+    };
+};
+type ContextualSubjectMatch = {
+    subjectId: MemoryId;
+    label: string;
+    confidence: 'exact' | 'strong' | 'weak';
+    matchedBy: 'id' | 'label' | 'alias' | 'locator' | 'query_text';
+};
+type OwnerReviewAction = 'accept' | 'edit_and_accept' | 'split' | 'bundle' | 'reject' | 'defer' | 'request_evidence';
+type ContextualReviewPacket = {
+    contractVersion: 1;
+    packetId: string;
+    projectId: MemoryId;
+    generatedAt: Timestamp;
+    trigger: {
+        action?: string;
+        reason: string;
+        subjectMatches: ContextualSubjectMatch[];
+    };
+    proposal: {
+        id: MemoryId;
+        claim: string;
+        state: 'pending' | 'deferred';
+        proposedKind?: DecisionKind;
+        subjectIds: MemoryId[];
+        origin: ProposalRecord['origin']['mode'];
+    };
+    authority: 'unaccepted';
+    presentation: 'advisory' | 'surface_before_action';
+    implementation: {
+        state: 'none_found' | 'attempted' | 'completed' | 'mixed';
+        attemptIds: MemoryId[];
+    };
+    evidence: {
+        sourceCount: number;
+        sourceRefs: SourceReference[];
+    };
+    actions: OwnerReviewAction[];
+    expansionRefs: SourceReference[];
+    estimatedTokens: number;
+};
+type ContextualReviewSelection = {
+    packets: ContextualReviewPacket[];
+    subjectMatches: ContextualSubjectMatch[];
+    completeness: {
+        status: 'complete' | 'truncated';
+        consideredProposalCount: number;
+        omittedPacketCount: number;
+        maxEstimatedTokens: number;
+        estimatedTokens: number;
+    };
+    uncertainty?: 'subject_unresolved' | 'no_relevant_pending_proposal';
+};
+declare function selectContextualReviewPackets(bundle: ProjectMemoryBundle, query: ContextualReviewQuery): ContextualReviewSelection;
+
+type RetrievalQuery = {
+    action?: string;
+    text?: string;
+    subjectIds?: MemoryId[];
+    subjectHints?: string[];
+    maxEstimatedTokens?: number;
+    maxDecisions?: number;
+    retrievedAt?: string;
+    candidateDecisionIds?: MemoryId[];
+};
+declare function retrieveActionPacket(bundle: ProjectMemoryBundle, query: RetrievalQuery): RetrievalPacket;
+
+type ImprintExplanationState = 'emerging' | 'testing' | 'grounded' | 'challenged' | 'retired';
+type ImprintSummaryKind = 'added' | 'strengthened' | 'refined' | 'challenged' | 'exception' | 'consolidated';
+type ImprintThreadSummary = {
+    transactionId: string;
+    coalescedTransactionIds?: string[];
+    additionalObservationCount?: number;
+    kind: ImprintSummaryKind;
+    title: string;
+    detail: string;
+    changes: Array<{
+        explanationId: string;
+        action: 'added' | 'revised' | 'supported' | 'challenged' | 'retired' | 'related';
+        statement: string;
+        state: ImprintExplanationState;
+    }>;
+    grounding?: {
+        explanationId: string;
+        question: string;
+        state: 'testing';
+    };
+    resolvedAction?: ImprintGroundingAction;
+};
+type ImprintGroundingAction = 'confirm' | 'reason_wrong' | 'narrow' | 'exception' | 'edit' | 'dont_learn' | 'undo';
+
+type MemoryReviewReceipt = {
+    status: 'committed' | 'not_ready' | 'rejected';
+    action: 'accept' | 'edit_and_accept' | 'reject' | 'defer';
+    proposalId: string;
+    decisionId?: string;
+    message: string;
+    headSequence?: number;
+};
+
+type EvalCaseStatus = 'pending' | 'approved' | 'rejected';
+type EvalCase = {
+    id: string;
+    title: string;
+    status: EvalCaseStatus;
+    category: 'component' | 'layout' | 'copy' | 'interaction' | 'visual' | 'workflow';
+    prompt: string;
+    assertions: string[];
+    rationale: string;
+    sourceDecisionIds: string[];
+    sourceThreadIds: string[];
+    dependencies?: EvalDependency[];
+    scenarios?: EvalScenario[];
+};
+type EvalRunStatus = 'pass' | 'fail' | 'needs_review';
+type EvalAssertionRunResult = {
+    assertion: string;
+    status: EvalRunStatus;
+    summary: string;
+    evidence: string[];
+};
+type EvalRunScope = {
+    type: 'current_page';
+    url: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+};
+type EvalRun = {
+    id: string;
+    evalId: string;
+    threadId?: string;
+    status: EvalRunStatus;
+    createdAt: number;
+    completedAt: number;
+    durationMs: number;
+    scope: EvalRunScope;
+    summary: string;
+    assertionResults: EvalAssertionRunResult[];
+    tooling: {
+        chromeDevtools: 'available' | 'unavailable' | 'unknown';
+        evidenceTypes: string[];
+    };
+    provider?: string;
+    model?: string;
+    screenshotPath?: string;
+    codeFingerprint?: string;
+    scopeFingerprint?: string;
+    rawResponse?: string;
+};
+
+type ConversationalReviewIntent = {
+    proposalId: string;
+    action: 'accept' | 'edit_and_accept' | 'reject' | 'defer';
+    kind?: DecisionKind;
+    claim?: string;
+    reason?: string;
+    taskContext?: string;
+    resurfaceWhen?: Array<'different_action' | 'new_evidence' | 'new_conflict' | 'owner_request'>;
+};
+
+type LegacyImportIssue = {
+    severity: 'info' | 'warning' | 'error';
+    code: string;
+    source?: string;
+    message: string;
+};
+type LegacyImportReport = {
+    projectRoot: string;
+    source: {
+        threads: number;
+        messages: number;
+        decisionEnvelopes: number;
+        modelEntries: number;
+        artifactsReferenced: number;
+    };
+    imported: Record<string, number>;
+    unresolvedAcceptance: number;
+    deferredModelEntries: number;
+    proofCases: Array<{
+        legacyId: string;
+        threadFound: boolean;
+        decisionEnvelopeFound: boolean;
+        recordIds: string[];
+    }>;
+    issues: LegacyImportIssue[];
+    schemaIssues: SchemaIssue[];
+};
+type LegacyImportOptions = {
+    projectRoot: string;
+    projectKey?: string;
+    proofCaseIds?: string[];
+    writerVersion?: string;
+};
+
+type CompletedJobCapture = {
+    jobId: string;
+    threadId: string;
+    createdAt: number;
+    completedAt: number;
+    requestSummary: string;
+    responseSummary?: string;
+    outcome: IterationOutcome;
+    execution: {
+        provider?: string;
+        model?: string;
+        sessionId?: string;
+    };
+    subjectHints: string[];
+    filePaths?: string[];
+    resolutions: Array<{
+        status: string;
+        summary: string;
+    }>;
+    /**
+     * Reusable semantic claims explicitly surfaced by the conversation layer.
+     * Ordinary successful resolutions are implementation evidence, not proposals.
+     */
+    semanticCandidates?: Array<{
+        claim: string;
+        rationale?: string;
+        proposedKind?: ProposalRecord['proposedKind'];
+        sourceText?: string;
+    }>;
+    /** Accepted decisions that materially guided this implementation attempt. */
+    governingDecisionIds?: string[];
+};
+
+type MemoryServiceStatus = {
+    initialized: boolean;
+    state: 'absent' | 'initializing' | 'ready' | 'degraded';
+    phase?: 'analyzing_legacy' | 'writing_checkpoint';
+    error?: string;
+    projectId?: string;
+    headSequence?: number;
+    updatedAt?: string;
+};
+type MemoryReviewResult = {
+    source: 'journal' | 'legacy_preview';
+    selection: ReturnType<typeof selectContextualReviewPackets>;
+};
+type MemoryContextResult = {
+    source: MemoryReviewResult['source'];
+    actionPacket: ReturnType<typeof retrieveActionPacket>;
+    reviewSelection: ReturnType<typeof selectContextualReviewPackets>;
+};
+type JournalEvalCase = EvalCase & {
+    canonicalSpecId: string;
+    verificationState: 'draft' | 'unverified' | 'passing' | 'failing' | 'needs_review' | 'stale' | 'retired';
+    verifiedScopeFingerprint?: string;
+    verificationAttemptId?: string;
+};
+declare class MemoryService {
+    private readonly projectRoot;
+    private readonly store;
+    private readonly manifestPath;
+    private readonly indexStore;
+    private initializationPromise?;
+    private runtimeState?;
+    constructor(projectRoot: string);
+    status(): Promise<MemoryServiceStatus>;
+    beginAutomaticInitialization(options?: {
+        projectKey?: string;
+        proofCaseIds?: string[];
+        writerVersion?: string;
+    }): Promise<MemoryServiceStatus>;
+    analyzeLegacy(options?: Omit<LegacyImportOptions, 'projectRoot'>): Promise<LegacyImportReport>;
+    /** One-time cutover import. Legacy eval files are never read during normal queries. */
+    migrateLegacyEvals(): Promise<{
+        migrated: boolean;
+        specs: number;
+        runs: number;
+    }>;
+    /** One-time identity/evidence bridge from the prototype Imprint journal. */
+    migrateImprintSnapshot(): Promise<{
+        migrated: boolean;
+        explanations: number;
+        evidence: number;
+    }>;
+    review(query: ContextualReviewQuery, options?: Omit<LegacyImportOptions, 'projectRoot'>): Promise<MemoryReviewResult>;
+    contextualize(query: ContextualReviewQuery, options?: Omit<LegacyImportOptions, 'projectRoot'>): Promise<MemoryContextResult>;
+    planReview(command: OwnerReviewCommand, options?: Omit<LegacyImportOptions, 'projectRoot'>): Promise<{
+        source: MemoryReviewResult['source'];
+        result: OwnerReviewPlanResult;
+    }>;
+    initializeFromLegacy(options: {
+        confirmed: boolean;
+        projectKey?: string;
+        proofCaseIds?: string[];
+        writerVersion?: string;
+    }): Promise<{
+        status: MemoryServiceStatus;
+        report: LegacyImportReport;
+    }>;
+    commitReview(command: OwnerReviewCommand, transaction: CommitReviewPlanOptions): Promise<MemoryJournalLoadResult>;
+    commitConversationalReview(intent: ConversationalReviewIntent): Promise<MemoryReviewReceipt>;
+    captureCompletedJob(capture: CompletedJobCapture): Promise<{
+        status: 'captured' | 'not_ready' | 'duplicate';
+        iterationId?: string;
+        proposalIds: string[];
+        headSequence?: number;
+    }>;
+    /**
+     * Mirrors Imprint identity and evidence into the canonical journal without
+     * promoting advisory explanations into product decisions.
+     */
+    recordImprintEvidence(input: {
+        summary: ImprintThreadSummary;
+        threadId: string;
+        jobId: string;
+        action?: ImprintGroundingAction;
+        occurredAt?: string;
+    }): Promise<void>;
+    recover(confirmed: boolean): Promise<MemoryJournalLoadResult>;
+    diagnostics(): Promise<{
+        status: MemoryServiceStatus;
+        journal?: MemoryJournalLoadResult['report'];
+        records?: Record<string, number>;
+        openFreshnessSignals?: number;
+        unavailableEvidence?: number;
+    }>;
+    getProjectableDecisions(limit?: number): Promise<DecisionRecord[]>;
+    getCanonicalModelEntries(): Promise<ModelEntryRecord[]>;
+    getModelView(): Promise<{
+        decisions: Array<{
+            id: string;
+            kind: string;
+            claim: string;
+            projected: boolean;
+            verification: string;
+        }>;
+        entries: Array<{
+            id: string;
+            key: string;
+            value: JsonValue;
+            decisionIds: string[];
+        }>;
+    }>;
+    getEvalDependenciesForDecisions(decisionIds: string[]): Promise<EvalDependency[]>;
+    recordDirectModelMutation(input: {
+        key: string;
+        value: JsonValue;
+        claim: string;
+    }): Promise<{
+        decisionId: string;
+        entryId: string;
+    }>;
+    syncEvalSpecs(cases: EvalCase[]): Promise<JournalEvalCase[]>;
+    getJournalEvalCases(): Promise<JournalEvalCase[]>;
+    findJournalEvalCase(id: string): Promise<JournalEvalCase | null>;
+    updateJournalEvalCase(id: string, patch: Partial<Pick<EvalCase, 'status' | 'title' | 'assertions'>>): Promise<JournalEvalCase | null>;
+    getJournalEvalRuns(): Promise<EvalRun[]>;
+    recordEvalVerification(evalCase: EvalCase, run: EvalRun): Promise<void>;
+    syncLegacyEvalRuns(cases: EvalCase[], runs: EvalRun[]): Promise<void>;
+    markEvalVerificationExpired(input: {
+        evalSpecId: string;
+        verificationAttemptId: string;
+        previousFingerprint?: string;
+        currentFingerprint?: string;
+    }): Promise<void>;
+    reconcileEvalCases(cases: EvalCase[]): Promise<{
+        valid: EvalCase[];
+        discardedIds: string[];
+    }>;
+    private latestEvalSpec;
+    findPendingProposalForLegacyDecision(legacyDecisionId: string): Promise<{
+        proposalId: string;
+        claim: string;
+    } | null>;
+    applyModelProjection(input: {
+        runId: string;
+        presentationJobId?: string;
+        decisionIds: string[];
+        changes: Array<{
+            path: Array<string | number>;
+            value: unknown;
+            decisionIds?: string[];
+            label?: string;
+        }>;
+        coverage?: Array<{
+            decisionId: string;
+            status: 'unprojected' | 'partially_projected' | 'projected';
+        }>;
+    }): Promise<{
+        projectionId: string;
+        entryIds: string[];
+        headSequence: number;
+    }>;
+    private loadSource;
+    private withIndexedCandidates;
+    private refreshIndex;
+}
+declare function parseOwnerReviewCommand(value: unknown): OwnerReviewCommand;
+declare function parseContextualReviewQuery(value: unknown): ContextualReviewQuery;
+
+export { type CommitReviewPlanOptions, type MemoryJournalLoadReport, type MemoryJournalLoadResult, type MemoryJournalManifest, type MemoryJournalMutation, MemoryJournalStore, type MemoryJournalTransaction, type MemoryReviewResult, MemoryService, type MemoryServiceStatus, computeTransactionHash, parseContextualReviewQuery, parseOwnerReviewCommand };