n8n-nodes-engram 0.5.1 → 0.7.0

package/README.md

@@ -19,13 +19,13 @@
   <a href="https://github.com/casistack/n8n-nodes-engram/blob/main/LICENSE">
     <img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="License: AGPL-3.0" />
   </a>
-  <img src="https://img.shields.io/badge/node-%3E%3D18.10-brightgreen.svg" alt="Node.js" />
+  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js" />
   <img src="https://img.shields.io/badge/n8n-community%20node-ff6d5a.svg" alt="n8n community node" />
 </p>
 
 <p align="center">
   <a href="#installation">Installation</a> &middot;
-  <a href="#upgrading-from-v04x">Upgrade</a> &middot;
+  <a href="#upgrading-to-v070">Upgrade</a> &middot;
   <a href="#node-reference">Nodes</a> &middot;
   <a href="#storage-backends">Storage</a> &middot;
   <a href="#knowledge-extraction">Extraction</a> &middot;
@@ -101,6 +101,110 @@ npm install n8n-nodes-engram
 
 ---
 
+## Upgrading to v0.7.0
+
+These Memory v2 controls are optional. Existing workflows keep **Entity Resolution > Legacy**, **Knowledge Selection > Legacy**, **Extraction Execution > Synchronous** and **Graph Context Policy > Legacy**. Installing a newer package does not enable them or rewrite existing knowledge.
+
+### Back Up and Install v0.7.0
+
+1. Back up current workflows and n8n configuration. Preserve exact namespace keys and any existing alias mapping.
+2. **Embedded:** pause writers and preserve each producer workflow's graph file, storage directory and workflow-to-file mapping. Use a separate restored store for upgrade trials. Once durable work exists, use **Extraction Queue > Export Queue Backup** for portable queue-aware recovery.
+3. **Neo4j:** take a consistent database backup using your normal recovery procedure. Retain the same database and namespace identities. Graph writers coordinate through a shared store lock; validate concurrent write throughput during rollout.
+4. Install `n8n-nodes-engram@0.7.0`, restart n8n, refresh the editor and confirm the installed version. Node.js 20 or newer is required. Existing v2 stores load without a bulk migration or re-extraction; earlier provenance/schema upgrades remain separate.
+5. Run **Engram Admin > Monitoring > Diagnostics**. Saved Memory v1 nodes remain v1; upgrade selected nodes explicitly to **Memory v2** on an inactive workflow copy before enabling the new controls. Check that the copy points to the intended restored store.
+
+### Activate Bounded Extraction First
+
+Back up current workflows and both the graph and conversation records before changing settings. Preserve the exact namespace, including whitespace, and the existing embedded workflow-to-file mapping or Neo4j database. Begin with one conversation workflow and keep the current model, session identity and conversation window.
+
+Select **Entity Resolution > Bounded** and **Message Write Policy > Final Turns**. Keep eligible human/final-assistant sources stored; system/tool extraction is unsupported in this mode. Exact names and explicitly verified aliases resolve before model comparisons. Defaults limit each extraction to an eight-candidate shortlist, 16 fuzzy comparisons, 32 model/embedding requests and a 30-second shared deadline. Identity ambiguity, pruned candidates and exhausted budgets remain proposed or deferred; they are not permission to merge existing identities. Legacy contradiction expiry and automatic summary updates are not performed by the bounded path.
+
+Select **Knowledge Selection > Durable and Temporal** to keep temporary requests in conversation history without automatically accepting them as durable facts. Automatic acceptance requires accepted human provenance and complete, literal assertion evidence. Paraphrases, quotations, hypothetical or qualified statements and uncertain identities require review. This conservative policy can produce more proposed records. It does not reclassify, re-extract or delete previously stored facts. **Source Timezone** must be an explicit IANA zone such as `Europe/London`; omit it when unknown. Calendar-day resolution supports today/tomorrow/yesterday and a single explicit date. Other relative expressions remain uncertain.
+
+**Graph Context Policy > Governed Current** reconciles search/traversal duplicates by relationship UUID, omits ungrounded entity summaries and excludes unresolved or out-of-interval plans from current context. **Governed Historical** retains historical evidence with source attribution; map historical intent explicitly in the workflow. **Governed As Of** requires an ISO timestamp with `Z` or a numeric offset and tests event-interval relevance, not what the system knew at that time. Separate **Durable Fact Token Allowance** (4096) and **Historical Evidence Token Allowance** (2048) stay within the overall graph context token cap; the recent-message window remains independent. A zero allowance disables that evidence category. Governed search and traversal share a 512-source-reference hydration allowance; candidates whose complete provenance does not fit are deferred, with `source_reference_deferred` and truncation diagnostics. Existing accepted legacy records are not automatically corrected. Genuine human JSON and quoted conversation remain in the episode ledger.
+
+Inspect save diagnostics for per-stage elapsed time, model-call counts, available token usage, candidate/deferral counts and storage timing. Unavailable provider/backend measurements are `null`; overlapping stage/request/storage times must not be added together. Agree latency targets from your own normal and tool-assisted workloads before expanding the rollout.
+
+### Activate a Durable Extraction Worker
+
+Durable Queue removes model extraction from the chat save path by persisting the episode and its extraction job together. Graph facts become available only after a worker completes. It requires persistent storage, bounded resolution, Final Turns and **Retention Policy > Keep Forever**; unsupported combinations fail before the write. Use stable per-turn message/idempotency keys for retries.
+
+1. Create a separate workflow with **Schedule Trigger > Engram Admin v2 > Extraction Queue > Process Jobs**. Start with **Worker Batch Size > 1**; each execution processes at most ten jobs sequentially. No worker runs automatically merely because the package is installed.
+2. Configure the same backend and exact **Queue Group ID** as Memory. For embedded storage, set **Memory Workflow ID** to the original producer workflow ID and use the same custom storage directory. The worker's own workflow ID is not the producer's store. The existing producer file must be present. For Neo4j, use the same database and appropriate credentials.
+3. Match the producer's extraction credential endpoint, model, temperature mode/value, entity types, thresholds, embedding configuration and all bounded/quality settings. Set the same nonsecret **Extraction Route ID** on producer and worker. API keys are not stored in jobs; credential rotation can retain the binding when these settings are unchanged. Route URLs containing credentials, query strings or fragments are rejected.
+4. Activate the scheduled worker, then select **Extraction Execution > Durable Queue** on the producer. Inspect `delivery.status=queued`, job IDs, enqueue timing and `graph_fresh=false`; this is not a successful extraction result. Use **Extraction Queue > Status** for pending/failed counts, oldest pending time and bounded job summaries, then inspect worker outcomes and actual graph facts.
+5. Verify an ordinary turn, a real tool-assisted turn, a durable preference, older-fact recall and an explicit historical query. Confirm the final pair is saved once, audits remain outside conversational context, original records retain their identity and the queue drains. Only then activate additional namespaces. Evaluate passive ingestion separately.
+
+Jobs use fenced leases, bounded retry/backoff and atomic graph/completion writes. Restarts can recover work; retries do not resend chat messages. Configuration mismatch leaves work unclaimed. Use **Rebind Job** with an operator and reason only after reviewing corrected settings; this preserves the source/job identity and clears stale staged work. Pause, resume, retry and cancel are explicit reviewed operations. Capacity or durable-storage failures can reject the conversation write; monitor workflow errors rather than assuming every queued save is fail-soft. Snapshot preparation is capped at 100,000 records/100 MiB; source, request, response and staged-plan byte limits can defer oversized work without truncating original messages.
+
+### Backups, Historical Artifacts and Rollback
+
+Use **Extraction Queue > Export Queue Backup** to preserve jobs, ownership and completion markers along with graph/episode records. A generic graph export alone is not the queue recovery procedure. Imports verify checksums, namespace/endpoints and collisions; incomplete legacy source/chain references are retained with warnings. Imported active jobs are paused pending configuration review. Creating a fresh embedded import destination requires explicit review and a custom directory. Never import over newer live conversations.
+
+The historical-artifact inspection and dry-run steps below still apply. This feature does not reinterpret historical records already labelled as genuine conversation, automatically delete extracted facts or provide a record-specific correction migration.
+
+For rollback, first stop producers and workers and take a fresh queue-aware backup. Prefer restoring the previous policy settings on the new package. Before using an older binary, complete or explicitly cancel outstanding jobs and verify no worker remains active. Older binaries do not enforce queue ownership, leases or disk-sync protections; do not run old and new writers concurrently against a queue-bearing store. Keep the queue-aware backup and all new legitimate records. If an older package cannot safely read the retained operational metadata, use a separately reviewed recovery/export procedure; never overwrite live history with an old snapshot as routine rollback. Existing no-queue embedded stores retain their prior disk-sync behavior. Neo4j graph writers coordinate through a shared store lock to protect atomic extraction commits; measure concurrent write throughput before expanding a busy deployment.
+
+---
+
+## Upgrading to v0.6.0
+
+**Installing this release makes the controls available; it does not automatically activate history filtering or final-turn writes.** Existing saved settings retain temperature `0`, History Filter `Off`, Message Write Policy `Legacy`, and Store Tool Audit `Disabled`. Saved Memory v1 nodes remain v1 until explicitly upgraded. The temperature control is available in both v1 and v2; the history/write/query controls require Memory v2.
+
+### Back Up and Install
+
+1. Back up your workflows and n8n instance configuration using your normal recovery procedure. Create current Engram exports and backend backups before changing package or node settings.
+2. **Embedded:** preserve each workflow's graph file while writes are paused, or take a consistent Engram export. Keep the original storage directory, workflow-to-file mapping, and session/group keys. A copied workflow can have a different default storage filename; validate against a separately restored test copy rather than accidentally testing a new empty graph.
+3. **Neo4j:** take a database backup or consistent export using your normal Neo4j recovery procedure. Keep the same database, credentials, and session/group keys for the existing deployment.
+4. Upgrade the existing community-node installation to `n8n-nodes-engram@0.6.0`, restart n8n, refresh the editor, and confirm the installed version. Node.js 20 or newer is required by the package.
+5. For stores already running `0.5.1`, this release requires **no storage schema migration** on either backend. Run **Engram Admin > Monitoring > Diagnostics** to confirm storage health. If upgrading from `0.4.x` or earlier, complete the existing provenance/schema migration instructions separately.
+
+### Activate Deliberately, One Memory Workflow at a Time
+
+Start with one backed-up direct-conversation workflow, then validate before updating the remaining Memory nodes. If it still uses Memory v1, use n8n's node upgrade action in an inactive workflow copy to adopt **Memory v2**. Preserve its intended storage and canonical session key; do not replace session keys or use display-name changes as an identity migration.
+
+| Setting | Initial activation |
+| --- | --- |
+| Extraction Temperature Mode | Select **Provider Default** when the extraction model rejects temperature `0`; this truly omits the request field. Otherwise retain a mode supported by that model. |
+| History Filter | Select **Provenance** to exclude known tool-output, monitor-summary, and audit episodes from context. |
+| Message Write Policy | Select **Final Turns** to apply storage/extraction controls to both normal saves and native bulk tool-assisted saves. |
+| Store Tool Audit | Keep **Disabled** initially. Enable only if audit retention is needed; retained audits stay outside conversation context under Final Turns. |
+| Current Human Query | Map to the same current-human-message expression used by the agent prompt. The default accepts string `chatInput`, then string `input`; a different webhook shape needs an explicit mapping. |
+| Store Human / AI Episodes | Review the intended retention; both default to Enabled in v2. |
+| Extract from Human / AI / System and Tool Content | Human extraction defaults Enabled; AI and System/Tool extraction default Disabled. Review these when upgrading a v1 node. |
+| Human Episode Kind | Keep **Active Human** for direct conversations; use **Passive Human** for observed/curated human ingestion. |
+| Source Message ID / Idempotency Key | Use a stable **per-message/per-turn** identity for retry deduplication. A static session key or phone number is not a turn identity and can collapse distinct messages. |
+
+The context window counts messages/episodes, not user turns or days. With filtering enabled, older eligible messages refill that window within **Maximum History Scan** (default 1000, maximum 10000). Load diagnostics distinguish snapshot overflow from scan-budget truncation. n8n subnode expressions can have different item-resolution behavior from regular nodes; validate mappings for independent conversations rather than assuming a batch resolves each item separately.
+
+### Historical Artifacts: Inspect and Dry-Run First
+
+This release does not delete historical episodes or graph facts. Provenance filtering cannot automatically prove that an unlabelled legacy JSON message is a tool artifact.
+
+1. Use **Engram Explorer > Episode > List/Get** with the exact group, date, and provenance filters to inspect candidate records, their source identities, and `previous_episode_uuid` links. Preserve genuine human JSON, quoted content, and ambiguous messages.
+2. For a bounded preview, use **Engram Admin > Lifecycle > Purge Episodes**, keep **Execution Mode > Dry Run**, and set the same exact group/provenance/date scope with a small **Maximum Episodes** limit. **Malformed Content Rule > Empty Assistant Output** can locate empty assistant records; inspect their neighboring episodes separately. **Content Contains** should use a distinctive reviewed marker, not generic JSON keys. Do not select **Delete** or confirm a purge as part of this upgrade. Dry-run results are preview candidates, not automatic approval for deletion or filtering.
+3. There is no separate History Filter dry-run switch. Preview filtering in an **inactive workflow copy backed by a separate restored store**, compare its Memory load output before/after, and inspect `history.excluded_legacy`, `legacy_candidates`, `returned`, and `scan_truncated`.
+4. If an exact legacy payload is confirmed to be an artifact, calculate its lowercase SHA256 from the **exact UTF-8 episode content**, including whitespace. Select **History Filter > Provenance and Reviewed Legacy** and add that digest to **Reviewed Legacy Content Hashes** (up to 100 comma-separated hashes). A matching hash still requires strict legacy role, adjacency, chain, and source checks. The neighboring empty assistant and reviewed payload are excluded only from context; original records and facts remain intact. Unapproved or ambiguous JSON stays visible.
+
+### Verify Before Expanding the Rollout
+
+- **Extraction:** inspect the Memory save/bulk-write `extraction` outcome and verify expected accepted entities/relationships in Explorer. A green overall chat execution or a valid empty extraction response alone does not prove fact creation.
+- **Older recall:** query a known older accepted fact after its episode has fallen outside the recent-message window. Confirm the configured current query and relevant graph context, including any governance filters.
+- **Tool-assisted conversation:** exercise a real tool, confirm the real human/final-assistant messages are retained, and verify tool results are not new human sources. Inspect bulk write and extraction diagnostics.
+- **Filtered history:** confirm useful messages refill the window, reviewed exclusions match expectations, genuine JSON/quotes remain, and scan truncation is understood. Re-run one explicit turn identity to check retry behavior without reusing that identity for new turns.
+
+After these checks pass, apply the intended controls to the remaining Memory nodes in stages. Extraction and persistence are not a transactional exactly-once pipeline: retrying an already-stored source does not automatically recover extraction interrupted after persistence. Storage-disabled extraction has no durable retry ledger.
+
+### Rollback
+
+Keep the pre-upgrade workflows, exports, and backend backups unchanged until rollout validation finishes. To roll back, pause writes, restore the saved workflow configuration, reinstall `n8n-nodes-engram@0.5.1` through the same installation method, and restart n8n. This returns the prior behavior, including its extraction-model limitations.
+
+No store restore is required merely to undo a non-destructive history filter. However, if **Store Tool Audit** was enabled, `0.5.1` does not implement the new audit-context exclusion and may replay those new records. Review that history before downgrading; keeping `0.6.0` with the intended controls or using a separately restored pre-upgrade store may be preferable. Turning filtering off does not delete audit records.
+
+If a store restore is necessary, use the backed-up embedded file/Engram export or your Neo4j recovery procedure while writes are paused. Reconcile messages created since the backup before replacing live data; restoring an older snapshot can discard newer conversations. Never wipe groups, trim/change session keys, or delete graph facts as an automatic rollback step.
+
+---
+
 ## Upgrading from v0.4.x
 
 Version `0.5.0` adds episode provenance and governance fields. Storage migration and n8n node-version upgrades are separate steps.
@@ -184,6 +288,7 @@ On each conversation turn, Engram Memory:
 | --- | --- | --- |
 | Storage Backend | Embedded (Graphology) or Neo4j | Embedded |
 | Knowledge Extraction | LLM-powered entity extraction | Disabled |
+| Extraction Temperature Mode | Legacy (0), Provider Default (omit), or Custom | Legacy (0) |
 | Store Human Episodes | Persist human messages as episodes (v2) | Enabled |
 | Human Episode Kind | Classify human input as active or passive provenance (v2) | Active Human |
 | Store AI Episodes | Persist assistant replies as episodes (v2) | Enabled |
@@ -191,13 +296,33 @@ On each conversation turn, Engram Memory:
 | Extract from AI Messages | Allow assistant content to produce facts (v2) | Disabled |
 | Semantic Search | Vector embeddings for hybrid search | Disabled |
 | Graph Traversal | BFS enrichment from matched entities | Disabled |
-| Context Window | Recent turns to include | 10 |
+| Context Window | Recent messages/episodes to include | 10 |
 | Max Facts per Query | Facts injected as context | 10 |
 | Min Relevance Score | Threshold for inclusion (0&ndash;1) | 0.5 |
 | Retention Policy | Episode lifecycle management | Forever |
 
 Existing saved Engram Memory nodes retain their original node version and behavior when the package is upgraded. Use n8n's node upgrade action on a workflow copy to adopt v2 controls. Passive ingestion workflows should select **Human Episode Kind > Passive Human**, while direct agent conversations should keep the default **Active Human** classification.
 
+### History Filtering and Final-Turn Writes (Memory v2)
+
+These controls are opt-in. Existing saved settings keep **History Filter > Off** and **Message Write Policy > Legacy**. Upgrade a v1 Memory node through n8n's node upgrade action on a workflow copy before adopting the v2 controls. Session keys and existing episodes are preserved.
+
+- Select **History Filter > Provenance** to exclude tool-output, monitor-summary, and audit episodes from conversation context.
+- Select **Provenance and Reviewed Legacy** to additionally exclude an exact reviewed legacy artifact pair: an empty assistant `[]` immediately chained to an unlabelled legacy human array of response/error objects. The human payload must match a configured **Reviewed Legacy Content Hash**, and source/chain checks must agree. Without that approval, ambiguous JSON remains. Genuine human JSON, quoted messages, and graph fact SystemMessages are retained.
+- **Reviewed Legacy Content Hashes** accepts up to 100 comma-separated lowercase SHA256 hashes of exact UTF-8 episode content, including its whitespace. Review the original episodes before supplying hashes. Filtering changes only the context read; it does not delete records, rewrite chains, or remove graph facts.
+
+The context window counts eligible messages. Engram captures one bounded recent-episode snapshot and scans it in local pages of 100, refilling from older eligible messages. **Maximum History Scan** defaults to 1000 and is capped at 10000; one extra prefetched episode supports boundary evidence and overflow detection. This is bounded snapshot prefetch with local paging, not backend cursor pagination. Load diagnostics show `fetched`, `examined`, `pages`, exclusion counts, and `returned`. `snapshot_overflow` means more history existed than the scan allowance; `scan_truncated` means that allowance prevented filling the window. No new appends are fetched during the scan.
+
+Select **Message Write Policy > Final Turns** to apply the same storage, extraction, and provenance controls when n8n saves a normal turn or calls the native bulk-message tool-save path. Engram retains real human input and the final assistant reply after identified tool calls have closed. Native tool/function messages and intermediate assistant tool calls are classified distinctly and never become human input. **Store Tool Audit** optionally retains those messages as unverified tool-output episodes; they stay outside conversation context even with History Filter set to Off. Tool extraction remains a separate explicit control and is disabled by default.
+
+Set a stable per-turn **Idempotency Key** or human **Source Message ID** to deduplicate retries across both write paths. Final-role keys are independent of intermediate tool count. Repeated identical turns without an explicit identity remain distinct. Existing stored sources are not re-extracted on an ordinary duplicate write; persistence followed by extraction is not a transactional exactly-once guarantee. If storage is disabled, extraction uses transient sources and has no durable retry ledger. Native bulk-save diagnostics report confirmed writes, duplicates, audits, skipped messages, and the extraction outcome.
+
+### Current Query for Empty Memory Loads
+
+Some n8n agent versions call memory loading with empty values. Configure **Current Human Query** to the same current-message expression used by the agent prompt. Its default reads string `chatInput`, then string `input`, and otherwise leaves the query empty. Explicit input passed by the agent takes precedence. Engram does not infer a current query from old history.
+
+The expression is resolved in n8n's subnode item context when memory is supplied. Subnode expression behavior can differ from regular-node per-item evaluation; process independent conversations separately and validate mappings in your workflow. Load diagnostics expose `retrieval.query_source` (`input`, `configured`, or `none`), query availability, and the number of graph fact context messages without including query text. If no current query is available, history still loads but graph search is not attempted. Validate graph recall with a known older accepted fact beyond the recent-message window.
+
 ### Engram Explorer
 
 > Regular node&mdash;CRUD operations on the knowledge graph.
@@ -289,6 +414,32 @@ User message + AI response
 
 Extracted entities and relationships include `attributes.engram_extraction` provenance metadata with source, extraction timestamp, confidence placeholder, review status, and related episode UUIDs where available.
 
+### Extraction Model Compatibility
+
+**Extraction Temperature Mode** applies to every extraction stage in Engram Memory v1 and v2:
+
+- **Legacy (0)** sends temperature `0` and preserves existing workflow behavior.
+- **Provider Default** omits the temperature field. Select this when your model rejects custom temperatures or requires its own default.
+- **Custom** sends the **Extraction Temperature** value. Use a finite number supported by your provider and model; supported ranges vary.
+
+Upgrading the package alone retains Legacy (0). To resolve an unsupported-temperature error, select Provider Default explicitly in the affected Memory node and validate the workflow before activating it. No storage migration or Memory node-version upgrade is required for these settings. Engram does not automatically change models or retry rejected requests with guessed settings. Extraction still uses Chat Completions JSON-object mode; confirm that your provider and model support it.
+
+### Extraction Outcomes
+
+In an execution, open the Engram Memory save output and inspect `extraction`. Conversation history saves before extraction, so an overall successful conversation can still have a failed extraction outcome.
+
+| Status | Meaning |
+| --- | --- |
+| `disabled` | Knowledge extraction is disabled. |
+| `skipped` | No eligible, nonempty source messages were selected. |
+| `succeeded` | Attempted stages completed; finding zero entities is also successful. |
+| `partial` | An optional stage failed, malformed records were excluded, or a required stage failed after some graph changes succeeded. |
+| `failed` | A required stage failed before any graph changes succeeded, or extraction configuration is missing. |
+
+Outcomes include duration, stage status, confirmed mutation counts, filtered/malformed record counts, and bounded error classifications such as `unsupported_parameter`, `authentication`, `rate_limit`, and `timeout`. Update counts include metadata-only updates; edge expirations are counted separately. Partial extraction does not roll back completed graph changes. Provider error bodies and message content are excluded from extraction error diagnostics; normal n8n conversation previews still contain message content.
+
+Extraction outcomes belong to their execution's save output. Engram Admin storage diagnostics do not provide a persistent extraction event history. A failed history preview is reported separately from the completed save. The context window counts messages, not user turns or days; graph recall operates independently of that window.
+
 ---
 
 ## Search

package/dist/descriptions.js

@@ -36,7 +36,7 @@ exports.contextWindowLengthProperty = {
     name: 'contextWindowLength',
     type: 'number',
     default: 5,
-    hint: 'How many past interactions the model receives as context',
+    hint: 'Number of recent messages (episodes) to include, not user turns or days',
 };
 exports.customStoragePathProperty = {
     displayName: 'Custom Storage Path',

package/dist/descriptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"descriptions.js","sourceRoot":"","sources":["../src/descriptions.ts"],"names":[],"mappings":";;;AAEa,QAAA,eAAe,GAAoB;IAC9C,WAAW,EAAE,YAAY;IACzB,IAAI,EAAE,eAAe;IACrB,IAAI,EAAE,SAAS;IACf,OAAO,EAAE;QACP;YAEE,IAAI,EAAE,uCAAuC;YAC7C,KAAK,EAAE,WAAW;YAClB,WAAW,EAAE,2CAA2C;SACzD;QACD;YAEE,IAAI,EAAE,cAAc;YACpB,KAAK,EAAE,WAAW;YAClB,WAAW,EAAE,4EAA4E;SAC1F;KACF;IACD,OAAO,EAAE,WAAW;CACrB,CAAC;AAEW,QAAA,kBAAkB,GAAoB;IACjD,WAAW,EAAE,KAAK;IAClB,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,EAAE;IACX,WAAW,EAAE,kDAAkD;IAC/D,cAAc,EAAE;QACd,IAAI,EAAE;YACJ,aAAa,EAAE,CAAC,WAAW,CAAC;SAC7B;KACF;CACF,CAAC;AAEW,QAAA,2BAA2B,GAAoB;IAC1D,WAAW,EAAE,uBAAuB;IACpC,IAAI,EAAE,qBAAqB;IAC3B,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,CAAC;IACV,IAAI,EAAE,0DAA0D;CACjE,CAAC;AAEW,QAAA,yBAAyB,GAAoB;IACxD,WAAW,EAAE,qBAAqB;IAClC,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,EAAE;IACX,WAAW,EAAE,cAAc;IAE3B,WAAW,EACT,+SAA+S;IACjT,cAAc,EAAE;QACd,IAAI,EAAE;YACJ,OAAO,EAAE,CAAC,UAAU,CAAC;SACtB;KACF;CACF,CAAC"}
+{"version":3,"file":"descriptions.js","sourceRoot":"","sources":["../src/descriptions.ts"],"names":[],"mappings":";;;AAEa,QAAA,eAAe,GAAoB;IAC9C,WAAW,EAAE,YAAY;IACzB,IAAI,EAAE,eAAe;IACrB,IAAI,EAAE,SAAS;IACf,OAAO,EAAE;QACP;YAEE,IAAI,EAAE,uCAAuC;YAC7C,KAAK,EAAE,WAAW;YAClB,WAAW,EAAE,2CAA2C;SACzD;QACD;YAEE,IAAI,EAAE,cAAc;YACpB,KAAK,EAAE,WAAW;YAClB,WAAW,EAAE,4EAA4E;SAC1F;KACF;IACD,OAAO,EAAE,WAAW;CACrB,CAAC;AAEW,QAAA,kBAAkB,GAAoB;IACjD,WAAW,EAAE,KAAK;IAClB,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,EAAE;IACX,WAAW,EAAE,kDAAkD;IAC/D,cAAc,EAAE;QACd,IAAI,EAAE;YACJ,aAAa,EAAE,CAAC,WAAW,CAAC;SAC7B;KACF;CACF,CAAC;AAEW,QAAA,2BAA2B,GAAoB;IAC1D,WAAW,EAAE,uBAAuB;IACpC,IAAI,EAAE,qBAAqB;IAC3B,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,CAAC;IACV,IAAI,EAAE,yEAAyE;CAChF,CAAC;AAEW,QAAA,yBAAyB,GAAoB;IACxD,WAAW,EAAE,qBAAqB;IAClC,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,EAAE;IACX,WAAW,EAAE,cAAc;IAE3B,WAAW,EACT,+SAA+S;IACjT,cAAc,EAAE;QACd,IAAI,EAAE;YACJ,OAAO,EAAE,CAAC,UAAU,CAAC;SACtB;KACF;CACF,CAAC"}

package/dist/embeddings/EmbeddingService.d.ts

@@ -1,3 +1,5 @@
+import { RequestBudget } from '../extraction/RequestBudget';
+import { type ExtractionDiagnostics } from '../extraction/ExtractionDiagnostics';
 export interface EmbeddingConfig {
     apiKey: string;
     baseUrl: string;
@@ -13,12 +15,14 @@ export interface EmbeddingResult {
     };
 }
 export declare class EmbeddingService {
+    private diagnostics?;
+    private budget?;
     private apiKey;
     private baseUrl;
     private model;
     private dimensions;
     private timeoutMs;
-    constructor(config: EmbeddingConfig);
+    constructor(config: EmbeddingConfig, diagnostics?: ExtractionDiagnostics | undefined, budget?: RequestBudget | undefined);
     embed(text: string): Promise<EmbeddingResult>;
     embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
 }

package/dist/embeddings/EmbeddingService.js

@@ -1,10 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EmbeddingService = void 0;
+const RequestBudget_1 = require("../extraction/RequestBudget");
 const url_1 = require("../utils/url");
+const ExtractionDiagnostics_1 = require("../extraction/ExtractionDiagnostics");
 class EmbeddingService {
-    constructor(config) {
+    constructor(config, diagnostics, budget) {
         var _a;
+        this.diagnostics = diagnostics;
+        this.budget = budget;
         this.apiKey = config.apiKey;
         this.baseUrl = (0, url_1.normalizeHttpBaseUrl)(config.baseUrl, 'Embedding API baseUrl');
         this.model = config.model;
@@ -16,49 +20,105 @@ class EmbeddingService {
         return results[0];
     }
     async embedBatch(texts) {
+        var _a, _b, _c, _d, _e, _f, _g;
         if (texts.length === 0)
             return [];
-        const url = `${this.baseUrl}/embeddings`;
-        const body = {
-            model: this.model,
-            input: texts,
-        };
-        if (this.dimensions) {
-            body.dimensions = this.dimensions;
-        }
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
-        let response;
+        const end = (_a = this.diagnostics) === null || _a === void 0 ? void 0 : _a.begin('embeddings');
+        let failed = true;
         try {
-            response = await fetch(url, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    Authorization: `Bearer ${this.apiKey}`,
-                },
-                body: JSON.stringify(body),
-                signal: controller.signal,
-            });
-        }
-        catch (error) {
-            if (error instanceof Error && error.name === 'AbortError') {
-                throw new Error(`Embedding API request timed out after ${this.timeoutMs}ms`);
+            const url = `${this.baseUrl}/embeddings`;
+            const body = {
+                model: this.model,
+                input: texts,
+            };
+            if (this.dimensions) {
+                body.dimensions = this.dimensions;
+            }
+            const serializedBody = JSON.stringify(body);
+            const remaining = (_b = this.budget) === null || _b === void 0 ? void 0 : _b.reserve(Buffer.byteLength(serializedBody));
+            const controller = new AbortController();
+            const abort = () => controller.abort();
+            (_c = this.budget) === null || _c === void 0 ? void 0 : _c.controller.signal.addEventListener('abort', abort, { once: true });
+            const timeout = setTimeout(abort, Math.min(remaining !== null && remaining !== void 0 ? remaining : this.timeoutMs, this.timeoutMs));
+            const metric = (_d = this.diagnostics) === null || _d === void 0 ? void 0 : _d.beginRequest('embeddings');
+            try {
+                let response;
+                try {
+                    response = await fetch(url, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                            Authorization: `Bearer ${this.apiKey}`,
+                        },
+                        body: serializedBody,
+                        signal: controller.signal,
+                    });
+                }
+                catch (error) {
+                    if (this.budget)
+                        throw new ExtractionDiagnostics_1.ExtractionError(controller.signal.aborted ? 'timeout' : 'network');
+                    if (error instanceof Error && error.name === 'AbortError') {
+                        throw new Error(`Embedding API request timed out after ${this.timeoutMs}ms`);
+                    }
+                    throw error;
+                }
+                metric === null || metric === void 0 ? void 0 : metric.headers();
+                if (!response.ok) {
+                    const errorText = this.budget
+                        ? await (0, RequestBudget_1.readBoundedResponse)(response, this.budget.maxResponseBytes)
+                        : await response.text();
+                    if (this.budget)
+                        throw new ExtractionDiagnostics_1.ExtractionError(response.status === 401 || response.status === 403
+                            ? 'authentication'
+                            : response.status === 429
+                                ? 'rate_limit'
+                                : response.status >= 500
+                                    ? 'provider_server'
+                                    : 'invalid_request', response.status);
+                    throw new Error(`Embedding API error (${response.status}): ${errorText}`);
+                }
+                const data = (this.budget
+                    ? JSON.parse(await (0, RequestBudget_1.readBoundedResponse)(response, this.budget.maxResponseBytes))
+                    : await response.json());
+                (_e = this.budget) === null || _e === void 0 ? void 0 : _e.check();
+                if (this.budget &&
+                    (!Array.isArray(data === null || data === void 0 ? void 0 : data.data) ||
+                        data.data.length !== texts.length ||
+                        data.data.some((item) => !item ||
+                            !Number.isInteger(item.index) ||
+                            item.index < 0 ||
+                            item.index >= texts.length ||
+                            !Array.isArray(item.embedding) ||
+                            !item.embedding.length ||
+                            !item.embedding.every(Number.isFinite)) ||
+                        new Set(data.data.map((item) => item.index)).size !== texts.length))
+                    throw new Error('Invalid embedding response');
+                const sorted = [...data.data].sort((a, b) => a.index - b.index);
+                metric === null || metric === void 0 ? void 0 : metric.end('completed', data.usage, true);
+                const results = sorted.map((item) => ({
+                    embedding: item.embedding,
+                    usage: data.usage,
+                }));
+                failed = false;
+                return results;
+            }
+            catch (error) {
+                if ((_f = this.budget) === null || _f === void 0 ? void 0 : _f.controller.signal.aborted)
+                    this.budget.check();
+                if (this.budget && controller.signal.aborted)
+                    throw new ExtractionDiagnostics_1.ExtractionError('timeout');
+                throw error;
+            }
+            finally {
+                if (failed)
+                    metric === null || metric === void 0 ? void 0 : metric.end(controller.signal.aborted ? 'cancelled' : 'failed', undefined, true);
+                clearTimeout(timeout);
+                (_g = this.budget) === null || _g === void 0 ? void 0 : _g.controller.signal.removeEventListener('abort', abort);
             }
-            throw error;
         }
         finally {
-            clearTimeout(timeout);
-        }
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Embedding API error (${response.status}): ${errorText}`);
+            end === null || end === void 0 ? void 0 : end(failed);
         }
-        const data = (await response.json());
-        const sorted = [...data.data].sort((a, b) => a.index - b.index);
-        return sorted.map((item) => ({
-            embedding: item.embedding,
-            usage: data.usage,
-        }));
     }
 }
 exports.EmbeddingService = EmbeddingService;

package/dist/embeddings/EmbeddingService.js.map

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

package/dist/extraction/AssertionEvidence.d.ts

@@ -0,0 +1 @@
+export declare function isDurableAssertion(content: string, start: number, end: number): boolean;

package/dist/extraction/AssertionEvidence.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDurableAssertion = isDurableAssertion;
+function isDurableAssertion(content, start, end) {
+    if (start < 0 || end <= start || end > content.length)
+        return false;
+    const text = content.slice(start, end).trim();
+    const before = content.slice(0, start).trimEnd();
+    const after = content.slice(end).trimStart();
+    if (before && !/[.!?\n]$/.test(before))
+        return false;
+    if (after && !/[.!?]$/.test(text))
+        return false;
+    if (content.includes('"') || /[“”]|^\s*>/m.test(content))
+        return false;
+    return (!text.includes('?') &&
+        !/\b(said|says|according to|hypothetical|might|maybe|not|never|false|denies|denied|without|no longer|if|unless|would|suppose|supposing|assuming|incorrect|untrue)\b|\b\w+n['’]t\b/i.test(text) &&
+        !/^\s*(what|when|where|which|who|how|can you|could you|please|tell me|show me|find me|asks?\b)/i.test(text) &&
+        !/\b(today|tomorrow|yesterday|later|next\s+(week|month|tuesday|monday|wednesday|thursday|friday|saturday|sunday)|this weekend)\b/i.test(text));
+}
+//# sourceMappingURL=AssertionEvidence.js.map

package/dist/extraction/AssertionEvidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssertionEvidence.js","sourceRoot":"","sources":["../../src/extraction/AssertionEvidence.ts"],"names":[],"mappings":";;AACA,gDAqBC;AArBD,SAAgB,kBAAkB,CAAC,OAAe,EAAE,KAAa,EAAE,GAAW;IAC5E,IAAI,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,KAAK,IAAI,GAAG,GAAG,OAAO,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACpE,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;IACjD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC;IAE7C,IAAI,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,KAAK,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IACvE,OAAO,CACL,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QACnB,CAAC,kLAAkL,CAAC,IAAI,CACtL,IAAI,CACL;QACD,CAAC,+FAA+F,CAAC,IAAI,CACnG,IAAI,CACL;QACD,CAAC,iIAAiI,CAAC,IAAI,CACrI,IAAI,CACL,CACF,CAAC;AACJ,CAAC"}

package/dist/extraction/BoundedExtraction.d.ts

@@ -0,0 +1,15 @@
+import { type EmbeddingConfig } from '../embeddings';
+import type { IGraphStorage } from '../storage/IGraphStorage';
+import { type ExtractionPolicyInput, type ExtractionThresholdPolicy } from '../schemas';
+import { type LlmClientConfig } from './LlmClient';
+import { ExtractionDiagnostics } from './ExtractionDiagnostics';
+import type { ExtractionSource } from './ExtractionSource';
+export declare function boundedExtract(storage: IGraphStorage, group: string, sources: ExtractionSource[], config: {
+    llm: LlmClientConfig;
+    policy?: ExtractionPolicyInput;
+    types: string[];
+    threshold?: ExtractionThresholdPolicy;
+    embeddings?: EmbeddingConfig;
+    signal?: AbortSignal;
+    deadlineMs?: number;
+}, diagnostics: ExtractionDiagnostics): Promise<void>;