@chude/memory 4.0.0 → 4.0.2

package/dist/domain/entities/memory-event.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Canonical memory event envelope.
+ *
+ * v5 event logs store these envelopes as source-of-truth records. Database
+ * tables and indexes are projections rebuilt from this canonical shape.
+ */
+import type { FactType } from "./fact.js";
+export declare const MEMORY_EVENT_SCHEMA_VERSION = 2;
+export type MemoryEventKind = FactType | "governance" | "privacy" | "consent" | "projection";
+export type MemoryEventOperation = "add" | "update" | "delete" | "supersede" | "noop" | "migrate";
+export type MemoryEventVisibility = "project" | "workspace" | "global";
+export type RedactionState = "none" | "redacted" | "quarantined";
+export type ConsentStatus = "not_required" | "granted" | "denied" | "revoked";
+export interface MemoryEventScope {
+    project?: string | undefined;
+    workspace?: string | undefined;
+    visibility: MemoryEventVisibility;
+}
+export interface MemoryEventProvenance {
+    source: string;
+    actor: string;
+    method: string;
+    sourceIds?: string[] | undefined;
+}
+export interface MemoryEventPrivacy {
+    redactionState: RedactionState;
+    containsSensitiveContent: boolean;
+    policy?: string | undefined;
+    redactedFields?: string[] | undefined;
+}
+export interface MemoryEventConsent {
+    status: ConsentStatus;
+    scopes: string[];
+    grantedAt?: Date | string | undefined;
+    expiresAt?: Date | string | undefined;
+}
+export interface MemoryEventCausality {
+    parentEventIds: string[];
+    supersedesEventIds: string[];
+    relatedEventIds: string[];
+}
+export interface MemoryEventIntegrity {
+    algorithm: "sha256";
+    payloadHash: string;
+    envelopeHash: string;
+}
+export interface MemoryEventCreateParams {
+    schemaVersion?: 2 | undefined;
+    eventId?: string | undefined;
+    machineId: string;
+    sequence: number;
+    kind: MemoryEventKind;
+    operation: MemoryEventOperation;
+    occurredAt: Date;
+    observedAt: Date;
+    scope: MemoryEventScope;
+    provenance: MemoryEventProvenance;
+    privacy: MemoryEventPrivacy;
+    consent: MemoryEventConsent;
+    causality: MemoryEventCausality;
+    payload: Record<string, unknown>;
+}
+export interface MemoryEventEnvelopeJson {
+    schemaVersion: 2;
+    eventId: string;
+    machineId: string;
+    sequence: number;
+    kind: MemoryEventKind;
+    operation: MemoryEventOperation;
+    occurredAt: string;
+    observedAt: string;
+    scope: MemoryEventScope;
+    provenance: MemoryEventProvenance;
+    privacy: MemoryEventPrivacy;
+    consent: MemoryEventConsent;
+    causality: MemoryEventCausality;
+    payload: Record<string, unknown>;
+    integrity: MemoryEventIntegrity;
+}
+export declare class MemoryEventEnvelope {
+    private readonly record;
+    private constructor();
+    static create(params: MemoryEventCreateParams): MemoryEventEnvelope;
+    static fromJSON(value: unknown): MemoryEventEnvelope;
+    get schemaVersion(): 2;
+    get eventId(): string;
+    get machineId(): string;
+    get sequence(): number;
+    get kind(): MemoryEventKind;
+    get operation(): MemoryEventOperation;
+    get occurredAt(): Date;
+    get observedAt(): Date;
+    get scope(): MemoryEventScope;
+    get provenance(): MemoryEventProvenance;
+    get privacy(): MemoryEventPrivacy;
+    get consent(): MemoryEventConsent;
+    get causality(): MemoryEventCausality;
+    get payload(): Record<string, unknown>;
+    get integrity(): MemoryEventIntegrity;
+    toJSON(): MemoryEventEnvelopeJson;
+}

package/dist/domain/entities/memory-governance.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Memory governance domain model.
+ *
+ * Tracks whether derived memory may be used on a given surface and preserves
+ * the provenance/consent/redaction state needed to explain that decision.
+ */
+import type { ConsentStatus, MemoryEventScope, MemoryEventVisibility, RedactionState } from "./memory-event.js";
+export declare const MEMORY_GOVERNANCE_SURFACES: readonly ["fact", "context", "provider_egress", "remote_sync", "friction", "evaluation", "persona", "graph", "ranking", "dream", "projection"];
+export type MemoryGovernanceSurface = (typeof MEMORY_GOVERNANCE_SURFACES)[number];
+export declare const MEMORY_GOVERNANCE_STATUSES: readonly ["active", "pending_review", "suppressed", "invalidated", "expired"];
+export type MemoryGovernanceStatus = (typeof MEMORY_GOVERNANCE_STATUSES)[number];
+export declare const MEMORY_GOVERNANCE_CONTROLS: readonly ["register", "suppress", "unsuppress", "invalidate", "expire", "review", "consent_grant", "consent_revoke"];
+export type MemoryGovernanceControl = (typeof MEMORY_GOVERNANCE_CONTROLS)[number];
+export interface MemoryGovernanceEntryParams {
+    id?: number | undefined;
+    surface: MemoryGovernanceSurface;
+    targetId: string;
+    project?: string | undefined;
+    visibility: MemoryEventVisibility;
+    sourceEventIds: string[];
+    transformationMethod: string;
+    actor: string;
+    confidence: number;
+    redactionState: RedactionState;
+    consentStatus: ConsentStatus;
+    consentScopes: string[];
+    scope: MemoryEventScope;
+    status?: MemoryGovernanceStatus | undefined;
+    statusReason?: string | undefined;
+    createdAt?: Date | undefined;
+    updatedAt?: Date | undefined;
+    reviewedAt?: Date | null | undefined;
+    expiresAt?: Date | null | undefined;
+    lastEventId?: string | undefined;
+}
+export interface GovernanceControlParams {
+    control: MemoryGovernanceControl;
+    actor: string;
+    reason?: string | undefined;
+    occurredAt: Date;
+    expiresAt?: Date | null | undefined;
+    consentStatus?: ConsentStatus | undefined;
+    consentScopes?: string[] | undefined;
+    lastEventId?: string | undefined;
+}
+export interface MemoryGovernanceEntryJson {
+    id?: number | undefined;
+    surface: MemoryGovernanceSurface;
+    target_id: string;
+    project?: string | undefined;
+    visibility: MemoryEventVisibility;
+    source_event_ids: string[];
+    transformation_method: string;
+    actor: string;
+    confidence: number;
+    redaction_state: RedactionState;
+    consent_status: ConsentStatus;
+    consent_scopes: string[];
+    scope: MemoryEventScope;
+    status: MemoryGovernanceStatus;
+    status_reason?: string | undefined;
+    created_at: string;
+    updated_at: string;
+    reviewed_at: string | null;
+    expires_at: string | null;
+    last_event_id?: string | undefined;
+    blocked: boolean;
+}
+export declare class MemoryGovernanceEntry {
+    private readonly params;
+    private constructor();
+    static create(params: MemoryGovernanceEntryParams): MemoryGovernanceEntry;
+    get id(): number | undefined;
+    get surface(): MemoryGovernanceSurface;
+    get targetId(): string;
+    get project(): string | undefined;
+    get visibility(): MemoryEventVisibility;
+    get sourceEventIds(): string[];
+    get transformationMethod(): string;
+    get actor(): string;
+    get confidence(): number;
+    get redactionState(): RedactionState;
+    get consentStatus(): ConsentStatus;
+    get consentScopes(): string[];
+    get scope(): MemoryEventScope;
+    get status(): MemoryGovernanceStatus;
+    get statusReason(): string | undefined;
+    get createdAt(): Date;
+    get updatedAt(): Date;
+    get reviewedAt(): Date | null;
+    get expiresAt(): Date | null;
+    get lastEventId(): string | undefined;
+    withId(id: number): MemoryGovernanceEntry;
+    withControl(params: GovernanceControlParams): MemoryGovernanceEntry;
+    isBlocked(now?: Date): boolean;
+    toJSON(now?: Date): MemoryGovernanceEntryJson;
+    toParams(): MemoryGovernanceEntryParams;
+}
+export declare function assertMemoryGovernanceSurface(value: string): MemoryGovernanceSurface;
+export declare function assertMemoryGovernanceControl(value: string): MemoryGovernanceControl;

package/dist/domain/entities/memory-utility-metric.d.ts

@@ -0,0 +1,65 @@
+export declare const MEMORY_UTILITY_SURFACES: readonly ["fact", "persona", "graph", "link", "dream"];
+export type MemoryUtilitySurface = (typeof MEMORY_UTILITY_SURFACES)[number];
+export declare const MEMORY_UTILITY_CONTROLS: readonly ["record_access", "rank", "pin", "mark_evergreen"];
+export type MemoryUtilityControl = (typeof MEMORY_UTILITY_CONTROLS)[number];
+export interface MemoryUtilityMetricParams {
+    id?: number | undefined;
+    surface: MemoryUtilitySurface;
+    targetId: string;
+    project?: string | undefined;
+    accessCount?: number | undefined;
+    lastAccessedAt?: Date | null | undefined;
+    lastRankedAt?: Date | null | undefined;
+    utilityScore?: number | undefined;
+    importanceScore?: number | undefined;
+    evergreen?: boolean | undefined;
+    pinned?: boolean | undefined;
+    halfLifeDays?: number | null | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    createdAt?: Date | undefined;
+    updatedAt?: Date | undefined;
+}
+export interface MemoryUtilityMetricJson {
+    id?: number | undefined;
+    surface: MemoryUtilitySurface;
+    target_id: string;
+    project?: string | undefined;
+    access_count: number;
+    last_accessed_at: string | null;
+    last_ranked_at: string | null;
+    utility_score: number;
+    importance_score: number;
+    evergreen: boolean;
+    pinned: boolean;
+    half_life_days: number | null;
+    metadata?: Record<string, unknown> | undefined;
+    controls: MemoryUtilityControl[];
+    created_at: string;
+    updated_at: string;
+}
+export declare class MemoryUtilityMetric {
+    private readonly params;
+    private constructor();
+    static create(params: MemoryUtilityMetricParams): MemoryUtilityMetric;
+    get id(): number | undefined;
+    get surface(): MemoryUtilitySurface;
+    get targetId(): string;
+    get project(): string | undefined;
+    get accessCount(): number;
+    get lastAccessedAt(): Date | null;
+    get lastRankedAt(): Date | null;
+    get utilityScore(): number;
+    get importanceScore(): number;
+    get evergreen(): boolean;
+    get pinned(): boolean;
+    get halfLifeDays(): number | null;
+    get metadata(): Record<string, unknown> | undefined;
+    get controls(): MemoryUtilityControl[];
+    get createdAt(): Date;
+    get updatedAt(): Date;
+    withId(id: number): MemoryUtilityMetric;
+    recordAccess(accessedAt: Date): MemoryUtilityMetric;
+    markRanked(rankedAt: Date): MemoryUtilityMetric;
+    toParams(): MemoryUtilityMetricParams;
+    toJSON(): MemoryUtilityMetricJson;
+}

package/dist/domain/entities/persona-entry.d.ts

@@ -0,0 +1,67 @@
+import type { MemoryEventScope, MemoryEventVisibility } from "./memory-event.js";
+export declare const PERSONA_ENTRY_KINDS: readonly ["preference", "procedure", "correction", "decision_pattern", "friction_pattern"];
+export type PersonaEntryKind = (typeof PERSONA_ENTRY_KINDS)[number];
+export type PersonaReviewStatus = "pending_review" | "reviewed";
+export declare const PERSONA_ENTRY_CONTROLS: readonly ["suppress", "invalidate", "expire", "review"];
+export interface PersonaEntryParams {
+    id?: number | undefined;
+    entryId: string;
+    kind: PersonaEntryKind;
+    content: string;
+    project?: string | undefined;
+    visibility: MemoryEventVisibility;
+    sourceEventIds: string[];
+    sourceKinds: string[];
+    confidence: number;
+    scope: MemoryEventScope;
+    reviewStatus: PersonaReviewStatus;
+    reviewAfter: Date;
+    expiresAt?: Date | null | undefined;
+    why: string;
+    createdAt?: Date | undefined;
+    updatedAt?: Date | undefined;
+}
+export interface PersonaEntryJson {
+    id?: number | undefined;
+    entry_id: string;
+    kind: PersonaEntryKind;
+    content: string;
+    project?: string | undefined;
+    visibility: MemoryEventVisibility;
+    source_event_ids: string[];
+    source_kinds: string[];
+    confidence: number;
+    scope: MemoryEventScope;
+    review_status: PersonaReviewStatus;
+    review_after: string;
+    expires_at: string | null;
+    why: string;
+    controls: string[];
+    created_at: string;
+    updated_at: string;
+}
+export declare class PersonaEntry {
+    private readonly params;
+    private constructor();
+    static create(params: PersonaEntryParams): PersonaEntry;
+    get id(): number | undefined;
+    get entryId(): string;
+    get kind(): PersonaEntryKind;
+    get content(): string;
+    get project(): string | undefined;
+    get visibility(): MemoryEventVisibility;
+    get sourceEventIds(): string[];
+    get sourceKinds(): string[];
+    get confidence(): number;
+    get scope(): MemoryEventScope;
+    get reviewStatus(): PersonaReviewStatus;
+    get reviewAfter(): Date;
+    get expiresAt(): Date | null;
+    get why(): string;
+    get controls(): string[];
+    get createdAt(): Date;
+    get updatedAt(): Date;
+    withId(id: number): PersonaEntry;
+    toJSON(): PersonaEntryJson;
+    toParams(): PersonaEntryParams;
+}

package/dist/domain/ports/capability.d.ts

@@ -0,0 +1,35 @@
+export type CapabilitySignal = "env-injection" | "masked-metadata" | "proofs" | "fingerprints";
+export type CapabilityProviderStatusValue = "available" | "optional_unavailable" | "reference_only";
+export type CapabilityReferenceStatus = "env_available" | "reference_only" | "plaintext_config_deprecated";
+export type CapabilitySecretSource = "environment" | "plaintext-config" | "missing";
+export interface MaskedCapabilityReference {
+    scheme: string;
+    provider: string;
+    maskedReference: string;
+    fingerprint: string;
+}
+export interface CapabilityProviderStatus {
+    provider: string;
+    optional: boolean;
+    available: boolean;
+    status: CapabilityProviderStatusValue;
+    statusSource: "path" | "reference";
+    allowedSignals: CapabilitySignal[];
+    rawSecretAccess: "forbidden";
+    warnings: string[];
+}
+export interface CapabilityReferenceStatusReport extends MaskedCapabilityReference {
+    source: "embedding.apiKeyRef";
+    runtimeSecretSource: CapabilitySecretSource;
+    status: CapabilityReferenceStatus;
+    envVar?: string | undefined;
+    note: string;
+}
+export interface CapabilityInteropStatus {
+    providers: CapabilityProviderStatus[];
+    references: CapabilityReferenceStatusReport[];
+    warnings: string[];
+}
+export interface ICapabilityStatusProvider {
+    getStatus(): CapabilityInteropStatus;
+}

package/dist/domain/ports/embedding.d.ts

@@ -9,6 +9,27 @@
  * value objects and primitive types.
  */
 import type { EmbeddingResult } from "../value-objects/embedding-result.js";
+/**
+ * Stable provider error categories the application layer can react to without
+ * knowing provider-specific transport details.
+ */
+export type EmbeddingProviderErrorKind = "payload_too_large" | "provider_error";
+export interface EmbeddingProviderErrorOptions {
+    kind: EmbeddingProviderErrorKind;
+    message: string;
+    status?: number | undefined;
+    retryable?: boolean | undefined;
+    metadata?: Record<string, string | number | boolean | null> | undefined;
+    cause?: unknown;
+}
+export declare class EmbeddingProviderError extends Error {
+    readonly kind: EmbeddingProviderErrorKind;
+    readonly status?: number | undefined;
+    readonly retryable: boolean;
+    readonly metadata: Record<string, string | number | boolean | null>;
+    constructor(options: EmbeddingProviderErrorOptions);
+}
+export declare function isEmbeddingProviderError(error: unknown, kind?: EmbeddingProviderErrorKind): error is EmbeddingProviderError;
 /**
  * Progress update during model download or initialization.
  */

package/dist/domain/ports/index.d.ts

@@ -7,6 +7,7 @@
 export type { ISessionRepository, IMessageRepository, IToolUseRepository, ILinkRepository, IExtractionStateRepository, IEmbeddingRepository, IMemoryFileRepository, IFrictionRepository, IBackfillStateRepository, BackfillStatusCounts, FrictionStats, UnembeddedMessage, EmbeddingBatchItem, EmbeddingServiceConfig, IFactRepository, IExtractionLogRepository, ExtractionLogEntry, } from "./repositories.js";
 export type { IEmbeddingProvider, DownloadProgress, EmbeddingModelInfo, } from "./embedding.js";
 export type { IExtractionProvider, } from "./extraction.js";
+export type { CapabilityInteropStatus, CapabilityProviderStatus, CapabilityProviderStatusValue, CapabilityReferenceStatus, CapabilityReferenceStatusReport, CapabilitySecretSource, CapabilitySignal, ICapabilityStatusProvider, MaskedCapabilityReference, } from "./capability.js";
 export type { IRedactor, JsonRedactionResult, RedactionFinding, RedactionKind, RedactionResult, } from "./redactor.js";
 export type { ISearchService, SearchOptions, SearchMode, HybridSearchOptions, IStatsService, StatsResult, ProjectStats, ISummaryGenerator, QmdSearchResult, QmdHealthInfo, IExternalSearchProvider, IAmbientContextWriter, } from "./services.js";
 export type { ISessionSource, IEventParser, IProjectNameResolver, IMemoryFileScanner, SessionFileInfo, MemoryFileInfo, } from "./sources.js";

package/dist/domain/ports/redactor.d.ts

@@ -2,6 +2,9 @@ export type RedactionKind = "api_key" | "aws_access_key" | "bearer_token" | "env
 export interface RedactionFinding {
     kind: RedactionKind;
     placeholder: string;
+    hash?: string | undefined;
+    ruleVersion?: string | undefined;
+    path?: string | undefined;
 }
 export interface RedactionResult {
     text: string;

package/dist/domain/ports/repositories.d.ts

@@ -20,6 +20,11 @@ import type { FrictionEntry, FrictionSeverity, FrictionStatus } from "../entitie
 import type { BackfillState } from "../entities/backfill-state.js";
 import type { ProjectPath } from "../value-objects/project-path.js";
 import type { Fact } from "../entities/fact.js";
+import type { PersonaEntry, PersonaEntryKind } from "../entities/persona-entry.js";
+import type { GraphEdge } from "../entities/graph-edge.js";
+import type { MemoryUtilityMetric, MemoryUtilitySurface } from "../entities/memory-utility-metric.js";
+import type { MemoryGovernanceEntry, MemoryGovernanceStatus, MemoryGovernanceSurface } from "../entities/memory-governance.js";
+import type { MemoryEventEnvelope } from "../entities/memory-event.js";
 /**
  * Options for filtering session list.
  */
@@ -342,6 +347,38 @@ export interface EmbeddingBatchItem {
     /** The embedding vector */
     embedding: Float32Array;
 }
+export type EmbeddingSkipReason = "payload_too_large";
+/**
+ * Durable model-scoped record for messages the current provider/model cannot
+ * embed safely. It deliberately stores a content hash and byte size instead of
+ * raw content so skip state remains useful without becoming a leakage surface.
+ */
+export interface EmbeddingSkipRecordInput {
+    /** The integer rowid matching messages_meta.rowid */
+    messageId: number;
+    /** Hash identifying the provider/model/dimension configuration */
+    modelHash: string;
+    /** Human-readable model name */
+    modelName: string;
+    /** Provider identifier */
+    provider: string;
+    /** Stable skip reason */
+    reason: EmbeddingSkipReason;
+    /** Whether retrying the exact same item/model is expected to help */
+    retryable: boolean;
+    /** SHA-256 hash of the original message content */
+    contentHash: string;
+    /** UTF-8 byte size of the original message content */
+    contentBytes: number;
+    /** Sanitized provider/application error context */
+    safeError?: string | undefined;
+    /** Optional explicit skip timestamp */
+    skippedAt?: Date | string | undefined;
+}
+export interface EmbeddingSkipRecord extends EmbeddingSkipRecordInput {
+    id: number;
+    skippedAt: string;
+}
 /**
  * Domain-layer configuration contract for the embedding service.
  *
@@ -359,6 +396,8 @@ export interface EmbeddingServiceConfig {
     dimensions: number;
     /** Number of messages to process per batch */
     batchSize: number;
+    /** Maximum estimated JSON payload bytes to send in a provider request */
+    maxBatchBytes?: number | undefined;
 }
 /**
  * Repository port for embedding data access.
@@ -381,7 +420,18 @@ export interface IEmbeddingRepository {
      * @param limit Maximum number of messages to return
      * @returns Array of unembedded messages ordered by rowid ASC
      */
-    findUnembedded(limit: number): UnembeddedMessage[];
+    findUnembedded(limit: number, modelHash?: string): UnembeddedMessage[];
+    /**
+     * Persist a model-scoped skipped message without storing raw message content.
+     * @param record Sanitized skip metadata
+     */
+    markSkipped(record: EmbeddingSkipRecordInput): void;
+    /**
+     * Count skipped messages, optionally for a specific model hash.
+     * @param modelHash Optional model hash filter
+     * @returns Number of skipped message records
+     */
+    getSkippedCount(modelHash?: string): number;
     /**
      * Store a batch of embeddings in a single transaction.
      * @param items Array of embedding batch items (rowid + vector)
@@ -493,6 +543,79 @@ export interface FrictionPattern {
     count: number;
     entries: FrictionEntry[];
 }
+/**
+ * Durable friction query options.
+ */
+export interface FrictionQueryOptions {
+    status?: FrictionStatus | undefined;
+    severity?: FrictionSeverity | undefined;
+    category?: string | undefined;
+    tool?: string | undefined;
+    sourceProject?: string | undefined;
+    since?: Date | undefined;
+    descriptionContains?: string | undefined;
+    contextContains?: string | undefined;
+    limit?: number | undefined;
+}
+/**
+ * Durable friction query result.
+ */
+export interface FrictionQueryResult {
+    entries: FrictionEntry[];
+    totalCount: number;
+}
+export interface PersonaListOptions {
+    project?: string | undefined;
+    visibility?: "project" | "workspace" | "global" | undefined;
+    kind?: PersonaEntryKind | undefined;
+    limit?: number | undefined;
+}
+export interface PersonaContextOptions {
+    includeGlobal?: boolean | undefined;
+    limit?: number | undefined;
+}
+export interface IPersonaRepository {
+    save(entry: PersonaEntry): Promise<PersonaEntry>;
+    saveMany(entries: PersonaEntry[]): Promise<PersonaEntry[]>;
+    findByEntryId(entryId: string): Promise<PersonaEntry | null>;
+    findAll(options?: PersonaListOptions): Promise<PersonaEntry[]>;
+    findForContext(project: string, options?: PersonaContextOptions): Promise<PersonaEntry[]>;
+    deleteByProject(project: string): Promise<void>;
+    clearAll(): Promise<void>;
+}
+export interface GraphEdgeQueryOptions {
+    project?: string | undefined;
+    includeGlobal?: boolean | undefined;
+    asOf?: Date | undefined;
+    minConfidence?: number | undefined;
+    nodeId?: string | undefined;
+    relationship?: string | undefined;
+    limit?: number | undefined;
+}
+export interface IGraphRepository {
+    save(edge: GraphEdge): Promise<GraphEdge>;
+    saveMany(edges: GraphEdge[]): Promise<GraphEdge[]>;
+    findByEdgeId(edgeId: string): Promise<GraphEdge | null>;
+    findCurrent(options?: GraphEdgeQueryOptions): Promise<GraphEdge[]>;
+    pruneStale(cutoff: Date): Promise<number>;
+    deleteByProject(project: string): Promise<void>;
+    clearAll(): Promise<void>;
+}
+/**
+ * Repository for utility/ranking metrics across governed memory surfaces.
+ *
+ * Metrics are keyed by surface + target id so ranking can work for existing
+ * facts/persona/graph entries and future dream/link projections without adding
+ * per-surface coupling to context assembly.
+ */
+export interface IMemoryUtilityRepository {
+    save(metric: MemoryUtilityMetric): Promise<MemoryUtilityMetric>;
+    findByTarget(surface: MemoryUtilitySurface, targetId: string): Promise<MemoryUtilityMetric | null>;
+    findByTargetIds(surface: MemoryUtilitySurface, targetIds: string[]): Promise<MemoryUtilityMetric[]>;
+    recordAccess(surface: MemoryUtilitySurface, targetId: string, accessedAt: Date): Promise<MemoryUtilityMetric>;
+    deleteByProject(project: string): Promise<void>;
+    clearAll(): Promise<void>;
+}
 /**
  * Repository for FrictionEntry entities.
  *
@@ -529,6 +652,13 @@ export interface IFrictionRepository {
         sourceProject?: string;
         limit?: number;
     }): Promise<FrictionEntry[]>;
+    /**
+     * Query friction entries with stable durable contract semantics.
+     * Returns totalCount before limit is applied.
+     * @param options Durable query filters
+     * @returns Matching entries and total matching count
+     */
+    query(options?: FrictionQueryOptions): Promise<FrictionQueryResult>;
     /**
      * Resolve a friction entry with a resolution description.
      * @param id The entry database ID
@@ -656,3 +786,27 @@ export interface IExtractionLogRepository {
     findAll(): Promise<ExtractionLogEntry[]>;
     clearAll(): Promise<void>;
 }
+/**
+ * Options for listing governed derived memory entries.
+ */
+export interface MemoryGovernanceListOptions {
+    surface?: MemoryGovernanceSurface | undefined;
+    targetId?: string | undefined;
+    project?: string | undefined;
+    status?: MemoryGovernanceStatus | undefined;
+    limit?: number | undefined;
+}
+/**
+ * Repository for consent/provenance governance state.
+ *
+ * This stores the current projection of control events. Canonical event logs
+ * remain the source of truth; this projection makes policy checks cheap.
+ */
+export interface IMemoryGovernanceRepository {
+    save(entry: MemoryGovernanceEntry): Promise<MemoryGovernanceEntry>;
+    findByTarget(surface: MemoryGovernanceSurface, targetId: string): Promise<MemoryGovernanceEntry | null>;
+    findByTargetIds(surface: MemoryGovernanceSurface, targetIds: string[]): Promise<MemoryGovernanceEntry[]>;
+    findAll(options?: MemoryGovernanceListOptions): Promise<MemoryGovernanceEntry[]>;
+    applyMemoryEvent(event: MemoryEventEnvelope): Promise<MemoryGovernanceEntry | null>;
+    clearAll(): Promise<void>;
+}

package/dist/domain/ports/sources.d.ts

@@ -79,7 +79,7 @@ export interface IProjectNameResolver {
     /**
      * Resolve a project name from a full encoded path.
      *
-     * @param encodedPath The encoded directory path (e.g., "C--Users-Destiny-Projects-memory-nexus")
+     * @param encodedPath The encoded directory path (e.g., "C--Projects-memory-nexus")
      * @returns The resolved project name (e.g., "memory-nexus")
      */
     resolveFromEncodedPath(encodedPath: string): string;

package/dist/domain/services/path-decoder.d.ts

@@ -13,7 +13,7 @@ import { ProjectPath } from "../value-objects/index.js";
 export declare class PathDecoder {
     /**
      * Decode an encoded project directory name to a ProjectPath value object.
-     * @param encoded The encoded directory name (e.g., "C--Users-Destiny-Projects-foo")
+     * @param encoded The encoded directory name (e.g., "C--Projects-foo")
      * @returns ProjectPath value object with decoded path
      */
     static decodeProjectDirectory(encoded: string): ProjectPath;

package/dist/domain/value-objects/project-path.d.ts

@@ -34,13 +34,13 @@ export declare class ProjectPath {
     private constructor();
     /**
      * Create ProjectPath from a decoded (original) path.
-     * @param path The original filesystem path (e.g., "C:\Users\Destiny\Projects\foo")
+     * @param path The original filesystem path (e.g., "C:\Projects\foo")
      * @throws Error if path is empty or whitespace-only
      */
     static fromDecoded(path: string): ProjectPath;
     /**
      * Create ProjectPath from an encoded path.
-     * @param encoded The encoded path (e.g., "C--Users-Destiny-Projects-foo")
+     * @param encoded The encoded path (e.g., "C--Projects-foo")
      * @throws Error if path is empty or whitespace-only
      */
     static fromEncoded(encoded: string): ProjectPath;

package/dist/index.d.ts

@@ -10,6 +10,6 @@
  */
 export * from "./domain/index.js";
 export * from "./application/index.js";
-export { executeSyncCommand, executeSearchCommand, executeListCommand, executeStatsCommand, executeContextCommand, executeRelatedCommand, executeShowCommand, executeBrowseCommand, executeQueryCommand, executeInstallCommand, executeUninstallCommand, executeStatusCommand, executeDoctorCommand, executePurgeCommand, executeExportCommand, executeImportCommand, executeCompletionCommand, executeFrictionCommand, } from "./presentation/cli/commands/index.js";
+export { executeSyncCommand, executeSearchCommand, executeListCommand, executeStatsCommand, executeContextCommand, executeRelatedCommand, executeShowCommand, executeBrowseCommand, executeQueryCommand, executeInstallCommand, executeUninstallCommand, executeStatusCommand, executeDoctorCommand, executeAuditSecretsCommand, executePurgeCommand, executeExportCommand, executeImportCommand, executeCompletionCommand, executeFrictionCommand, } from "./presentation/cli/commands/index.js";
 export type { CommandResult } from "./presentation/cli/commands/index.js";
-export type { SyncCommandOptions, EmbeddingPassDeps, BackgroundModeDeps, SearchCommandOptions, ListCommandOptions, StatsCommandOptions, ContextCommandOptions, RelatedCommandOptions, ShowCommandOptions, QueryCommandOptions, BrowseCommandOptions, InstallOptions, UninstallOptions, DoctorOptions, PurgeCommandOptions, PurgeResult, ExportOptions, ImportOptions, ShellType, StatusInfo, EmbeddingStatus, StatusOptions, GatherStatusOptions, FrictionCommandOptions, FrictionLogOptions, FrictionListOptions, FrictionResolveOptions, FrictionExecuteOptions, } from "./presentation/cli/commands/index.js";
+export type { SyncCommandOptions, EmbeddingPassDeps, BackgroundModeDeps, SearchCommandOptions, ListCommandOptions, StatsCommandOptions, ContextCommandOptions, RelatedCommandOptions, ShowCommandOptions, QueryCommandOptions, BrowseCommandOptions, InstallOptions, UninstallOptions, DoctorOptions, AuditSecretsOptions, PurgeCommandOptions, PurgeResult, ExportOptions, ImportOptions, ShellType, StatusInfo, EmbeddingStatus, StatusOptions, GatherStatusOptions, FrictionCommandOptions, FrictionLogOptions, FrictionListOptions, FrictionResolveOptions, FrictionExecuteOptions, } from "./presentation/cli/commands/index.js";