@hy-sde-org/dsh-memory-extraction 0.1.2-rc.1

package/dist/types.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Vocabulary for automatic long-term-memory extraction (Maka port, slice No. 2):
+ * the frozen source snapshot, evidence records, proposal items, admission
+ * results, and the durable cursor / receipt / pending-failure records the
+ * pipeline commits through.
+ *
+ * The pipeline is additive to DSH's explicit `retain`/`learn`/`memory_edit`
+ * surface — same `ctx.memory` store, one new trigger (compaction checkpoints).
+ * Maka's 8-facet memory-item schema (kind/statementType/temporalType/scope/
+ * keys) is deliberately NOT ported: DSH's bank stores plain content + context
+ * + source + importance. The Maka discipline that IS load-bearing — verbatim
+ * quote admission, deterministic policy rejection, canonicalization
+ * re-admission, bounded evidence, deterministic operation ids — lives in
+ * `evidence.ts`/`proposal.ts`/`engine.ts` unchanged.
+ * @module @hy-sde-org/dsh-memory-extraction/types
+ */
+/** v1 triggers only `compaction`; `remember`/`extract` are reserved (Maka names, not ported as tools). */
+export type MemoryExtractionTrigger = 'compaction';
+export type MemoryExtractionGate = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: 'disabled' | 'ineligible' | 'unavailable';
+};
+/**
+ * Frozen extraction request. The runtime builds it from the live session at
+ * trigger time and freezes exactly the facts the pipeline may read; the engine
+ * never touches the live session after this point.
+ */
+export interface MemoryExtractionSourceSnapshot {
+    readonly trigger: MemoryExtractionTrigger;
+    readonly sessionId: string;
+    /** Durable boundary: the seq of the triggering `compaction/summary` event. */
+    readonly boundarySeq: number;
+    /** Absolute project cwd for the memory commit (session header). */
+    readonly workspaceKey?: string;
+    /** Routed provider/model for the auxiliary call (session request header). */
+    readonly provider?: string;
+    readonly model?: string;
+    /** Gate facts: subagent children are policy-denied from the automatic path. */
+    readonly origin?: 'subagent';
+    readonly delegationDepth?: number;
+}
+/**
+ * One session-log entry reduced to the portable text facts the engine needs.
+ * The runtime adapter projects real `SessionEvent`s into this shape, so the
+ * engine stays testable without a live `Session`. Anything the adapter does
+ * not carry (tool calls, thinking, attachments, provider metadata) is
+ * deliberately outside the memory interpretation domain.
+ */
+export interface MemoryExtractionTextEvent {
+    /** Session seq — the pipeline's ordinal. */
+    readonly seq: number;
+    /** `user` / `assistant` / `other` (tool, plugin checkpoint, log marker). */
+    readonly role: 'user' | 'assistant' | 'other';
+    /** Producer identity: `user` (human), `model`, `plugin`, `tool`, `other`. */
+    readonly author: 'user' | 'model' | 'plugin' | 'tool' | 'other';
+    /** Joined text of the event's text content blocks; absent for non-text events. */
+    readonly text?: string;
+    /** Turn identity when the adapter can derive one (DSH turn number); absent otherwise. */
+    readonly turn?: number;
+    /** Unix epoch milliseconds. */
+    readonly time: number;
+}
+/** One seq-positioned entry in the event window. */
+export interface MemoryExtractionEventEntry {
+    readonly seq: number;
+    readonly event: MemoryExtractionTextEvent;
+}
+/** One bounded user-authored evidence record. */
+export interface MemoryExtractionEvidence {
+    /** Stable ref used in proposal citations: `event:<seq>`. */
+    readonly sourceRef: string;
+    readonly type: 'user_message';
+    /** Exactly the bounded text shown to the model and used for admission. */
+    readonly text: string;
+    readonly events: readonly MemoryExtractionTextEvent[];
+}
+/** The complete coverage plan for one trigger range. */
+export interface MemoryCoveragePlan {
+    readonly entries: readonly MemoryExtractionEventEntry[];
+    readonly evidence: readonly MemoryExtractionEvidence[];
+}
+/** One verbatim-cited evidence citation inside a proposal item. */
+export interface MemoryEvidenceCitation {
+    readonly sourceRef: string;
+    readonly quote: string;
+}
+/**
+ * One proposed memory item (stage 1). Maka's facet set is reduced to content
+ * + citations; admission enforces bounds, verbatim quotes, and policy.
+ */
+export interface MemoryProposalItem {
+    readonly content: string;
+    readonly evidence: readonly MemoryEvidenceCitation[];
+}
+/** Stage-1 result for an incidental (automatic) extraction. */
+export type MemoryProposal = {
+    readonly status: 'complete';
+    readonly incidents: readonly MemoryProposalItem[];
+} | {
+    readonly status: 'search_required';
+    readonly search: {
+        readonly terms: readonly string[];
+        readonly roles?: readonly ('user' | 'assistant')[];
+    };
+} | {
+    readonly status: 'cannot_resolve';
+};
+/** Localized (second-pass) result: complete or cannot_resolve. */
+export type LocalizedMemoryProposal = {
+    readonly status: 'complete';
+    readonly incidents: readonly MemoryProposalItem[];
+} | {
+    readonly status: 'cannot_resolve';
+};
+/** Canonicalization result: accept/rewrite or reject per candidate id. */
+export type MemoryCanonicalization = {
+    readonly results: readonly {
+        readonly candidateId: string;
+        readonly status: 'accepted' | 'rejected';
+        /** Rewritten durable content for `accepted` (admission re-runs against the original evidence quotes). */
+        readonly content?: string;
+    }[];
+};
+/** One admitted item ready to commit. */
+export interface AdmittedMemoryItem {
+    readonly content: string;
+    readonly citedSeqs: readonly number[];
+}
+/** Session-wide watermark: the highest seq already evaluated for memory. */
+export interface MemoryExtractionCursor {
+    readonly sessionId: string;
+    readonly processedSeq: number;
+    readonly updatedAt: number;
+}
+/** One frozen range retained for exactly one later retry. */
+export interface PendingMemoryExtractionFailure {
+    readonly sessionId: string;
+    readonly fromSeq: number;
+    readonly throughSeq: number;
+    readonly coverageHash: string;
+    readonly operationId: string;
+    readonly attempts: number;
+    readonly failureClass: MemoryExtractionFailureClass;
+    readonly failedAt: number;
+}
+export type MemoryExtractionFailureClass = 'provider' | 'schema' | 'evidence' | 'localization' | 'admission';
+export interface MemoryExtractionReceipt {
+    readonly operationId: string;
+    readonly sessionId: string;
+    readonly status: 'extracted' | 'skipped' | 'discarded';
+    /** Committed contents, in commit order (for the result message). */
+    readonly items: readonly string[];
+    readonly committedAt: number;
+}
+/** Ports request the range hash is verified against — the idempotency key. */
+export interface CommitMemoryExtractionRequest {
+    readonly operationId: string;
+    readonly sessionId: string;
+    readonly expectedCursorSeq: number;
+    readonly nextCursorSeq: number;
+    readonly coverageHash: string;
+    /** Admitted, canonicalized contents to commit. */
+    readonly items: readonly AdmittedMemoryItem[];
+    readonly trigger: MemoryExtractionTrigger;
+}
+export type SettleMemoryExtractionFailureResult = {
+    readonly status: 'retry_later';
+    readonly pending: PendingMemoryExtractionFailure;
+} | {
+    readonly status: 'discarded';
+    readonly cursor: MemoryExtractionCursor;
+};
+export interface SettleMemoryExtractionFailureRequest {
+    readonly operationId: string;
+    readonly sessionId: string;
+    readonly expectedCursorSeq: number;
+    readonly failedThroughSeq: number;
+    readonly coverageHash: string;
+    readonly failureClass: MemoryExtractionFailureClass;
+    readonly trigger: MemoryExtractionTrigger;
+}
+/** Result of one `engine.execute` run (fail-open by contract: never throws). */
+export type MemoryExtractionRunResult = {
+    readonly status: 'extracted';
+    readonly items: readonly string[];
+} | {
+    readonly status: 'skipped';
+} | {
+    readonly status: 'no_range';
+} | {
+    readonly status: 'unavailable';
+    readonly reason?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,18 @@
+/**
+ * Vocabulary for automatic long-term-memory extraction (Maka port, slice No. 2):
+ * the frozen source snapshot, evidence records, proposal items, admission
+ * results, and the durable cursor / receipt / pending-failure records the
+ * pipeline commits through.
+ *
+ * The pipeline is additive to DSH's explicit `retain`/`learn`/`memory_edit`
+ * surface — same `ctx.memory` store, one new trigger (compaction checkpoints).
+ * Maka's 8-facet memory-item schema (kind/statementType/temporalType/scope/
+ * keys) is deliberately NOT ported: DSH's bank stores plain content + context
+ * + source + importance. The Maka discipline that IS load-bearing — verbatim
+ * quote admission, deterministic policy rejection, canonicalization
+ * re-admission, bounded evidence, deterministic operation ids — lives in
+ * `evidence.ts`/`proposal.ts`/`engine.ts` unchanged.
+ * @module @hy-sde-org/dsh-memory-extraction/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@hy-sde-org/dsh-memory-extraction",
+  "description": "Automatic long-term-memory extraction at compaction checkpoints: evidence projection, proposal/canonicalization pipeline, gated ctx.memory commit, and durable cursors/receipts/failure ledger (Maka port, slice No. 2)",
+  "version": "0.1.2-rc.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/memory/memory-extraction"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-compaction": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-storage": "^0.1.2-rc.1",
+    "@hy-sde-org/dsh-memory": "^0.1.2-rc.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-compaction": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-storage": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-storage-sqlite": "^0.0.1-rc.1",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7",
+    "@hy-sde-org/dsh-memory": "0.1.2-rc.2"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}