@rubytech/create-siteoffice-code 0.1.256

package/payload/platform/plugins/memory/mcp/dist/lib/schema-validator.js

@@ -0,0 +1,243 @@
+/**
+ * Schema validator — validates memory-write inputs against two sources of
+ * truth:
+ *
+ *   1. `LiveSchemaSource` — recognised-label set = `db.labels()` snapshot
+ *      ∪ `schema.cypher` constraint/index declarations. This is the gate.
+ *      A label is recognised iff it appears in either set.
+ *   2. `LoadedSchema` (markdown sidecar) — required-property and naming-rule
+ *      metadata for documented labels. Markdown is no longer a label-existence
+ *      gate; required-property checks are skipped (with a log line) when the
+ *      label is recognised by the live source but absent from markdown.
+ *
+ * Checks run in order; first failure throws with a descriptive message.
+ *
+ *   1. accountId            — non-empty trimmed string
+ *   2. label existence      — at least one input label is in live ∪ declared.
+ *                             Rejection cites both sources and the nearest
+ *                             documented match (Levenshtein) when there is one
+ *   3. property synonym     — no property key is a known wrong-name alias.
+ *                             Runs before required-props so a `firstName`
+ *                             typo is reported as "rename firstName →
+ *                             givenName" rather than "missing givenName"
+ *   3b. forbidden property. Per-label deny-list parsed from the
+ *                             "Forbidden Properties" table in schema markdown.
+ *                             Fires AFTER the synonym pass so `firstName`
+ *                             still rewrites to `givenName` rather than
+ *                             rejecting on the wrong rule. First row:
+ *                             `Person | name`, eliminating the divergence
+ *                             trap where `name` truncated to `givenName`
+ *                             ("Dan") while the canonical pair held the full
+ *                             identity ("Dan Brett")
+ *   4. required properties  — for the primary label, fires only when the
+ *                             label is documented in markdown. Skipped (with
+ *                             a structured log line) when the label is
+ *                             recognised but undocumented — that's a
+ *                             stale-doc signal, not a write error
+ *
+ * The `[schema-validator]` log lines are the single observability surface.
+ * Operators reading server.log can distinguish "validation didn't run" from
+ * "validation passed" from "validation rejected" without source access.
+ *
+ * "Present" semantics for required-property values: defined, not null, and
+ * not a whitespace-only string. Numeric `0`, boolean `false`, and empty
+ * arrays count as present — the agent may legitimately persist those.
+ */
+import { nearestLabel } from "../../../../../lib/graph-mcp/dist/schema-cypher-parser.js";
+const BASE_SOURCE_FILE = "schema-base.md";
+/**
+ * A markdown rule is in scope for a write iff its sourceFile is the base
+ * schema OR matches the write's resolved vertical. A null resolved vertical
+ * narrows scope to base only — Maxy's non-vertical install enforces no
+ * vertical-specific rules.
+ */
+function isRuleInScope(sourceFile, resolvedVertical) {
+    if (sourceFile === BASE_SOURCE_FILE)
+        return true;
+    if (resolvedVertical === null)
+        return false;
+    return sourceFile === `${resolvedVertical}.md`;
+}
+/**
+ * Validate a write. Throws on the first violation. Caller is responsible
+ * for logging the thrown error in addition to the structured outcome lines
+ * this function emits — this stays a (mostly) pure unit so test fixtures
+ * can capture both the throw path and the emit stream.
+ */
+export function validateWrite(input, env, options = {}) {
+    const mode = options.mode ?? "create";
+    const verticalContext = options.verticalContext ?? {
+        resolvedVertical: null,
+        source: "brand-default",
+    };
+    const resolvedVertical = verticalContext.resolvedVertical;
+    const startedMs = Date.now();
+    const { labels, properties, accountId } = input;
+    const emit = env.emit ?? defaultEmit;
+    // Surface the resolved vertical once per write — every other validator
+    // line trails this so an operator reading server.log can read top-down
+    // and know which rules were in scope before any accept/reject outcome.
+    emit(`[schema-validator] resolved-vertical=${resolvedVertical ?? "none"} source=${verticalContext.source} accountId=${accountId ?? "<none>"}`);
+    // ---------------------------------------------------------------------
+    // 1. accountId non-empty
+    // ---------------------------------------------------------------------
+    if (typeof accountId !== "string" || accountId.trim().length === 0) {
+        throw new Error("memory-write: accountId is required and must be a non-empty string");
+    }
+    // ---------------------------------------------------------------------
+    // 2. At least one label is recognised by the live source
+    //    (recognised = live ∪ declared)
+    // ---------------------------------------------------------------------
+    if (!Array.isArray(labels) || labels.length === 0) {
+        throw new Error("memory-write: labels is required and must contain at least one Neo4j label");
+    }
+    const live = env.liveSource.liveLabels();
+    const declared = env.liveSource.declaredLabels();
+    const recognised = env.liveSource.recognisedLabels();
+    const hits = [];
+    for (const label of labels) {
+        if (recognised.has(label))
+            hits.push(label);
+    }
+    if (hits.length === 0) {
+        const liveList = [...live].sort().join(", ");
+        const declaredList = [...declared].sort().join(", ");
+        const suggestion = nearestLabel(labels[0], recognised);
+        const suggestionFragment = suggestion
+            ? ` Did you mean '${suggestion}'?`
+            : "";
+        const labelStr = labels.join(", ");
+        emit(`[schema-validator] check label=${primaryForLog(labels)} outcome=rejected source=neither ms=${Date.now() - startedMs}`);
+        throw new Error(`memory-write: unknown Neo4j label(s) [${labelStr}].${suggestionFragment} Live db.labels(): [${liveList}]. Declared in schema.cypher: [${declaredList}].`);
+    }
+    const primaryLabel = hits[0];
+    const inLive = live.has(primaryLabel);
+    const inDeclared = declared.has(primaryLabel);
+    const recognisedSource = inLive && inDeclared ? "both" : inLive ? "live" : "declared";
+    // ---------------------------------------------------------------------
+    // 3. No property key is a known Schema.org synonym (wrong name)
+    //
+    // Synonym map is independent of label — `firstName` is wrong on every
+    // Person variant. Runs even when the label is markdown-undocumented;
+    // the synonyms apply to property semantics, not to specific labels.
+    // ---------------------------------------------------------------------
+    for (const key of Object.keys(properties)) {
+        const hit = env.schema.wrongToCorrect.get(key);
+        if (hit && isRuleInScope(hit.sourceFile, resolvedVertical)) {
+            throw new Error(`memory-write: property name '${key}' is not Schema.org — use '${hit.correct}' instead (${hit.sourceFile} property naming rules)`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // 3b. Forbidden-property check — fires AFTER the synonym
+    //     pass so a `firstName` write still rewrites to `givenName` first
+    //     rather than being mis-rejected. The map is per-primary-label:
+    //     `name` is forbidden on `Person` only; other labels keep `name`
+    //     as a canonical property. Skipped when the label has no entry,
+    //     which is the case for every label until a "Forbidden Properties"
+    //     row is added in schema-base.md (or a vertical schema).
+    // ---------------------------------------------------------------------
+    const forbidden = env.schema.forbiddenByLabel.get(primaryLabel);
+    if (forbidden) {
+        for (const key of Object.keys(properties)) {
+            const hit = forbidden.get(key);
+            if (hit && isRuleInScope(hit.sourceFile, resolvedVertical)) {
+                emit(`[schema-validator] outcome=rejected label=${primaryLabel} property=${key} reason=forbidden writer=${pickWriter(properties)}`);
+                throw new Error(`memory-write: '${key}' is not a valid ${primaryLabel} property — ${hit.rationale} (${hit.sourceFile} Forbidden Properties).`);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------
+    // 4. Required-property check — only when the primary label is documented
+    //    in markdown. Markdown-undocumented labels (e.g. AdminUser,
+    //    LocalBusiness, KnowledgeDocument as of 2026-04-25) are accepted by
+    //    label existence but their property shape is the agent's responsibility
+    //    until a markdown row is added.
+    // ---------------------------------------------------------------------
+    const definition = env.schema.markdownLabels.get(primaryLabel);
+    if (!definition) {
+        emit(`[schema-validator] check label=${primaryLabel} mode=${mode} outcome=accepted source=${recognisedSource} ms=${Date.now() - startedMs}`);
+        emit(`[schema-validator] markdown-undocumented label=${primaryLabel}`);
+        return;
+    }
+    // The label is documented somewhere in the merged markdown set, but the
+    // documenting file may be a vertical other than the one active for this
+    // write. Treat that the same as markdown-undocumented from the validator's
+    // perspective — the rule simply does not apply — but log a distinct
+    // reason so operators can spot out-of-scope-vertical writes that may
+    // benefit from a base-schema row.
+    if (!isRuleInScope(definition.sourceFile, resolvedVertical)) {
+        emit(`[schema-validator] check label=${primaryLabel} mode=${mode} outcome=accepted source=${recognisedSource} ms=${Date.now() - startedMs}`);
+        emit(`[schema-validator] markdown-undocumented label=${primaryLabel} reason=out-of-scope-vertical definedIn=${definition.sourceFile} active=${resolvedVertical ?? "none"}`);
+        return;
+    }
+    // `mode: "update"` skips the required-property loop only.
+    // Synonym + forbidden-property checks above already ran. The accept-path
+    // log line carries `mode=update` so partial writes are distinguishable in
+    // forensics from full creates.
+    if (mode === "update") {
+        emit(`[schema-validator] check label=${primaryLabel} mode=update outcome=accepted source=${recognisedSource} ms=${Date.now() - startedMs}`);
+        return;
+    }
+    const effectiveProperties = {
+        ...properties,
+        accountId,
+    };
+    for (const group of definition.required) {
+        if (!groupIsSatisfied(group, effectiveProperties)) {
+            emit(`[schema-validator] required-props label=${primaryLabel} outcome=missing-group group=${formatGroupForLog(group)}`);
+            throw new Error(`memory-write: missing required property ${formatGroup(group)} for label ${primaryLabel} (${definition.sourceFile})`);
+        }
+    }
+    emit(`[schema-validator] required-props label=${primaryLabel} outcome=satisfied`);
+    emit(`[schema-validator] check label=${primaryLabel} mode=${mode} outcome=accepted source=${recognisedSource} ms=${Date.now() - startedMs}`);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function isPresent(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    return true;
+}
+function groupIsSatisfied(group, properties) {
+    if (group.kind === "simple") {
+        return isPresent(properties[group.name]);
+    }
+    return group.names.some((name) => isPresent(properties[name]));
+}
+function formatGroup(group) {
+    if (group.kind === "simple")
+        return `'${group.name}'`;
+    return group.names.map((n) => `'${n}'`).join(" or ");
+}
+function formatGroupForLog(group) {
+    if (group.kind === "simple")
+        return group.name;
+    return group.names.join("|");
+}
+/** Pick a representative label for the rejection log line. */
+function primaryForLog(labels) {
+    return labels[0] ?? "<empty>";
+}
+/**
+ * Best-effort writer attribution for the forbidden-property log line. Reads
+ * `createdByAgent` (the canonical writer field) and falls back to
+ * `createdByTool` so memory-write callers — which set the latter — still
+ * surface in the log. Unknown writes log `writer=unknown` rather than
+ * suppressing the line; the rate-by-writer signal stays usable.
+ */
+function pickWriter(properties) {
+    const agent = properties.createdByAgent;
+    if (typeof agent === "string" && agent.length > 0)
+        return agent;
+    const tool = properties.createdByTool;
+    if (typeof tool === "string" && tool.length > 0)
+        return tool;
+    return "unknown";
+}
+function defaultEmit(line) {
+    process.stderr.write(`${line}\n`);
+}
+//# sourceMappingURL=schema-validator.js.map

package/payload/platform/plugins/memory/mcp/dist/lib/schema-validator.js.map

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

package/payload/platform/plugins/memory/mcp/dist/lib/section-types.d.ts

@@ -0,0 +1,127 @@
+/** Identity sections — anchor to `:UserProfile` via natural edge per kind. */
+export declare const IDENTITY_SECTION_KINDS: readonly ["Position", "Education", "Credential", "Skill", "Biography"];
+/** Structural sections — anchored only via HAS_SECTION + NEXT, no anchor edge. */
+export declare const STRUCTURAL_SECTION_KINDS: readonly ["Preface", "Abstract", "Introduction", "TableOfContents", "Chapter", "Conclusion", "Appendix", "Bibliography", "Glossary", "Acknowledgments"];
+/** Contract-clause sections — anchored via HAS_SECTION + NEXT; Parties + Definitions get extra wiring. */
+export declare const CONTRACT_SECTION_KINDS: readonly ["Parties", "Recitals", "Definitions", "Scope", "Term", "Payment", "Confidentiality", "IntellectualProperty", "Warranties", "Indemnification", "Liability", "Termination", "GoverningLaw", "ForceMajeure", "Notices", "EntireAgreement", "Amendment", "Assignment", "Severability", "Signatures"];
+/** Standalone nodes — written as their own top-level node, not a `:Section`. */
+export declare const STANDALONE_NODE_KINDS: readonly ["Project"];
+/** Label-fallback kind — closure miss. The specialist supplies `classifierReason`. */
+export declare const SECTION_KIND_OTHER: "Other";
+/** Direction of the anchor edge relative to the typed node. */
+export type AnchorEdgeDirection = "from-anchor" | "to-anchor";
+/** Direction of a related-node edge relative to the typed node. */
+export type RelatedEdgeDirection = "outgoing" | "incoming";
+/**
+ * Which document-side node the related edge connects to:
+ * - `"section"` (default): the section node this entry lives under.
+ * - `"anchor"`: the document anchor (e.g. the `:Organization` the website
+ *   is about). Use this for typed-entity edges like `:FOUNDED` /
+ *   `:WORKS_AT` / `:INVESTED_IN` / `:ADVISES` whose typed-edge allowlist
+ *   forbids a `:Section` endpoint — Task 482.
+ */
+export type RelatedEdgeTarget = "section" | "anchor";
+/** A related entity the typed node connects to (e.g. Position → Organization). */
+export interface ClassifiedRelated {
+    /** Ontology label — verified against the loaded label set. */
+    kind: string;
+    /** Properties on the related node. */
+    properties: Record<string, unknown>;
+    /** Edge from the typed node to the related node. */
+    edge: {
+        type: string;
+        direction: RelatedEdgeDirection;
+        /**
+         * Optional target-node selector — defaults to `"section"` for
+         * backward compatibility. Set `"anchor"` to land the edge on the
+         * document anchor instead of the section node (Task 482).
+         */
+        targetMode?: RelatedEdgeTarget;
+        properties?: Record<string, unknown>;
+    };
+    /**
+     * When true, MERGE the related node on its identifying property
+     * (e.g. Organization on `name`); when false, CREATE.
+     * Defaults to true — entity reuse is the safer default.
+     */
+    merge?: boolean;
+}
+/** A single classified section of the document (every section is one `:Section` node). */
+export interface ClassifiedSection {
+    /** Section kind from the closed enumeration; becomes a secondary label on `:Section`. */
+    kind: string;
+    /** Short human-readable title for the section. */
+    title: string;
+    /**
+     * Section body text — omit on BOTH paths. The writer derives body
+     * server-side via `cachedText.slice(sourceStart, sourceEnd)`. Any value
+     * supplied here is logged and ignored; it must never be written to Neo4j.
+     *
+     * - Document path: source text is `extractCache.get(attachmentId).text`,
+     *   populated by `memory-ingest-extract` from the file on disk.
+     * - Conversation-archive path: source text is the per-session tempfile
+     *   written by `conversation-archive-ingest.mjs` at
+     *   `turnTextCachePath(conversationIdentity, archiveSha256, sessionIndex)`.
+     *
+     * Tasks 465 (document path) and 468 (chat path) closed the LLM-supplied
+     * body vector on both sides — the classifier emits offsets only.
+     */
+    body?: string;
+    /** 1-3 sentence summary, ≤500 chars; stored as `:Section.summary`. */
+    summary: string;
+    /** Whole-document character offsets — inclusive start, exclusive end. */
+    sourceStart: number;
+    sourceEnd: number;
+    /** Properties on the section node (excluding accountId/embedding/provenance). */
+    properties: Record<string, unknown>;
+    /**
+     * Edge from the document subject (anchor) to / from the section node.
+     * Null for structural and contract-clause kinds — anchored only via
+     * the implicit `(:KnowledgeDocument)-[:HAS_SECTION]->(:Section)` + `:NEXT`.
+     */
+    anchorEdge: {
+        type: string;
+        direction: AnchorEdgeDirection;
+        properties?: Record<string, unknown>;
+    } | null;
+    /** Other entities this section references (e.g. Position → Organization via AT). */
+    related?: ClassifiedRelated[];
+    /** For `kind === "Other"`: one-line description of what the section was about. */
+    classifierReason?: string;
+}
+/**
+ * A node the specialist emitted but could not edge naturally.
+ * Surfaced to the operator so they decide whether the orphan is intentional
+ * (rare, valid) or a missing edge (ontology gap).
+ */
+export interface OrphanCandidate {
+    /** Ontology label of the would-be node. */
+    kind: string;
+    /** Short human-readable label naming the entity (e.g. organisation name). */
+    label: string;
+    /** Why no natural edge was found for this node. */
+    reason: string;
+}
+/**
+ * Document-level edge proposed by the specialist (e.g. PARTY edges from
+ * a contract `:KnowledgeDocument` to its Party persons / organisations).
+ */
+export interface ClassifiedDocumentEdge {
+    type: string;
+    direction: "outgoing" | "incoming";
+    targetKind: string;
+    targetProperties: Record<string, unknown>;
+    /** Default true — MERGE Person/Organization on identifying property. */
+    merge?: boolean;
+}
+/** The classifier's full output — what the specialist passes to memory-ingest. */
+export interface ClassifierOutput {
+    documentSummary: string;
+    documentKeywords: string[];
+    sections: ClassifiedSection[];
+    orphanCandidates: OrphanCandidate[];
+    documentEdges?: ClassifiedDocumentEdge[];
+    /** Diagnostic count of related-node `kind` values dropped as ontology misses. */
+    hallucinatedRelated: number;
+}
+//# sourceMappingURL=section-types.d.ts.map

package/payload/platform/plugins/memory/mcp/dist/lib/section-types.d.ts.map

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

package/payload/platform/plugins/memory/mcp/dist/lib/section-types.js

@@ -0,0 +1,56 @@
+// Section / classifier-output type contract.
+//
+// Task 424 deleted the server-side llm-classifier and moved typed-section
+// production into the dispatched specialist's in-turn work. The shape this
+// file describes is now the contract between the specialist (which emits the
+// JSON) and `memory-ingest` (which writes it). Memory-ingest does not call
+// any LLM; it consumes whatever the specialist passes through the tool args.
+/** Identity sections — anchor to `:UserProfile` via natural edge per kind. */
+export const IDENTITY_SECTION_KINDS = [
+    "Position",
+    "Education",
+    "Credential",
+    "Skill",
+    "Biography",
+];
+/** Structural sections — anchored only via HAS_SECTION + NEXT, no anchor edge. */
+export const STRUCTURAL_SECTION_KINDS = [
+    "Preface",
+    "Abstract",
+    "Introduction",
+    "TableOfContents",
+    "Chapter",
+    "Conclusion",
+    "Appendix",
+    "Bibliography",
+    "Glossary",
+    "Acknowledgments",
+];
+/** Contract-clause sections — anchored via HAS_SECTION + NEXT; Parties + Definitions get extra wiring. */
+export const CONTRACT_SECTION_KINDS = [
+    "Parties",
+    "Recitals",
+    "Definitions",
+    "Scope",
+    "Term",
+    "Payment",
+    "Confidentiality",
+    "IntellectualProperty",
+    "Warranties",
+    "Indemnification",
+    "Liability",
+    "Termination",
+    "GoverningLaw",
+    "ForceMajeure",
+    "Notices",
+    "EntireAgreement",
+    "Amendment",
+    "Assignment",
+    "Severability",
+    "Signatures",
+];
+/** Standalone nodes — written as their own top-level node, not a `:Section`. */
+export const STANDALONE_NODE_KINDS = ["Project"];
+/** Label-fallback kind — closure miss. The specialist supplies `classifierReason`. */
+export const SECTION_KIND_OTHER = "Other";
+//# sourceMappingURL=section-types.js.map

package/payload/platform/plugins/memory/mcp/dist/lib/section-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-types.js","sourceRoot":"","sources":["../../src/lib/section-types.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,6EAA6E;AAC7E,2EAA2E;AAC3E,6EAA6E;AAE7E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,UAAU;IACV,WAAW;IACX,YAAY;IACZ,OAAO;IACP,WAAW;CACH,CAAC;AAEX,kFAAkF;AAClF,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,SAAS;IACT,UAAU;IACV,cAAc;IACd,iBAAiB;IACjB,SAAS;IACT,YAAY;IACZ,UAAU;IACV,cAAc;IACd,UAAU;IACV,iBAAiB;CACT,CAAC;AAEX,0GAA0G;AAC1G,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,SAAS;IACT,UAAU;IACV,aAAa;IACb,OAAO;IACP,MAAM;IACN,SAAS;IACT,iBAAiB;IACjB,sBAAsB;IACtB,YAAY;IACZ,iBAAiB;IACjB,WAAW;IACX,aAAa;IACb,cAAc;IACd,cAAc;IACd,SAAS;IACT,iBAAiB;IACjB,WAAW;IACX,YAAY;IACZ,cAAc;IACd,YAAY;CACJ,CAAC;AAEX,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,SAAS,CAAU,CAAC;AAE1D,sFAAsF;AACtF,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAgB,CAAC"}

package/payload/platform/plugins/memory/mcp/dist/lib/timeline-extractor.d.ts

@@ -0,0 +1,19 @@
+export type DateForm = "iso" | "dmy" | "my" | "in-year" | "bare-year" | "relative" | "quarter";
+export interface DatedStatement {
+    occurredAt: string;
+    summary: string;
+    /** The literal date phrase that triggered the match. Useful for diagnostics. */
+    matched: string;
+    /** Which heuristic matched. */
+    form: DateForm;
+}
+/**
+ * Extract every dated statement from `body`. One row per sentence containing
+ * the first parseable date in that sentence. Sentences without a date are
+ * dropped silently (the diagnostic count is the caller's concern).
+ *
+ * `reference` anchors relative forms ("yesterday", "two weeks ago", "Q3 last
+ * year"). Callers pass the message's createdAt; absent that, current time.
+ */
+export declare function extractDatedStatements(body: string | null | undefined, reference?: Date): DatedStatement[];
+//# sourceMappingURL=timeline-extractor.d.ts.map

package/payload/platform/plugins/memory/mcp/dist/lib/timeline-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-extractor.d.ts","sourceRoot":"","sources":["../../src/lib/timeline-extractor.ts"],"names":[],"mappings":"AA2BA,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/F,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,CAAC;CAChB;AAiJD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,SAAS,GAAE,IAAiB,GAC3B,cAAc,EAAE,CA0BlB"}

package/payload/platform/plugins/memory/mcp/dist/lib/timeline-extractor.js

@@ -0,0 +1,179 @@
+// Deterministic dated-statement extractor for Task 306.
+//
+// Reads a free-text body and returns one row per parseable dated statement.
+// Strictly deterministic — no LLM, no heuristics that could collapse to a
+// catch-all. The 305 typed-edge post-write hook upgrades `kind` from the
+// default "mentioned" to a more specific value asynchronously; until then
+// rows land as `mentioned`, which is the most-faithful default.
+//
+// Date forms recognised (in priority order):
+//   1. ISO date           — 2026-03-10, 2026/03/10
+//   2. Day-month-year     — 10 March 2026, 10 Mar 2026
+//   3. Month-year         — March 2026, Mar 2026
+//   4. "in YYYY"          — "in 2018"
+//   5. "since YYYY"       — "since 2018"
+//   6. Bare year          — 2018 (only when 1900-2099 and surrounded by word boundaries)
+//   7. Relative + quarter — yesterday / last Tuesday / two weeks ago / Q3 2024
+//      (Task 390 — delegated to parseRelativeDate against caller-supplied reference)
+//
+// Coarse forms (bare year, "in YYYY") parse to YYYY-01-01T00:00:00Z so the
+// `occurredAt` index is queryable. Day-precision forms parse exactly.
+// Relative forms resolve to a UTC day from the reference timestamp.
+//
+// A statement is the sentence containing the parsed date. Summaries
+// truncate to 500 chars at sentence boundaries when possible.
+import { parseRelativeDate } from "./relative-date.js";
+const MONTHS = {
+    jan: 1, january: 1,
+    feb: 2, february: 2,
+    mar: 3, march: 3,
+    apr: 4, april: 4,
+    may: 5,
+    jun: 6, june: 6,
+    jul: 7, july: 7,
+    aug: 8, august: 8,
+    sep: 9, sept: 9, september: 9,
+    oct: 10, october: 10,
+    nov: 11, november: 11,
+    dec: 12, december: 12,
+};
+const SUMMARY_MAX = 500;
+function pad(n) {
+    return n < 10 ? `0${n}` : String(n);
+}
+function isoDay(year, month, day) {
+    return `${year}-${pad(month)}-${pad(day)}T00:00:00Z`;
+}
+function isoMonth(year, month) {
+    return `${year}-${pad(month)}-01T00:00:00Z`;
+}
+function isoYear(year) {
+    return `${year}-01-01T00:00:00Z`;
+}
+function validYear(y) {
+    return y >= 1900 && y <= 2099;
+}
+function validMonth(m) {
+    return m >= 1 && m <= 12;
+}
+function validDay(d) {
+    return d >= 1 && d <= 31;
+}
+/** Split body into sentences (period / question / exclamation followed by space or end). */
+function splitSentences(body) {
+    return body
+        .split(/(?<=[.?!])\s+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function clampSummary(s) {
+    if (s.length <= SUMMARY_MAX)
+        return s;
+    // Truncate at the last sentence boundary inside the cap, else hard-truncate.
+    const sliced = s.slice(0, SUMMARY_MAX);
+    const lastBoundary = Math.max(sliced.lastIndexOf(". "), sliced.lastIndexOf("? "), sliced.lastIndexOf("! "));
+    if (lastBoundary > SUMMARY_MAX * 0.5) {
+        return sliced.slice(0, lastBoundary + 1);
+    }
+    return sliced.slice(0, SUMMARY_MAX - 1) + "…";
+}
+/**
+ * Returns null if the sentence has no parseable date; otherwise the first
+ * matching date and its ISO normalisation.
+ */
+function parseFirstDate(sentence, reference) {
+    // 1. ISO date: 2026-03-10 or 2026/03/10
+    const iso = sentence.match(/\b(\d{4})[-/](\d{1,2})[-/](\d{1,2})\b/);
+    if (iso) {
+        const y = Number(iso[1]);
+        const m = Number(iso[2]);
+        const d = Number(iso[3]);
+        if (validYear(y) && validMonth(m) && validDay(d)) {
+            return { occurredAt: isoDay(y, m, d), matched: iso[0], form: "iso" };
+        }
+    }
+    // 2. Day-month-year: "10 March 2026" / "10 Mar 2026"
+    const dmy = sentence.match(/\b(\d{1,2})\s+([A-Za-z]+)\s+(\d{4})\b/);
+    if (dmy) {
+        const d = Number(dmy[1]);
+        const m = MONTHS[dmy[2].toLowerCase()];
+        const y = Number(dmy[3]);
+        if (m && validYear(y) && validDay(d)) {
+            return { occurredAt: isoDay(y, m, d), matched: dmy[0], form: "dmy" };
+        }
+    }
+    // 3. Month-year: "March 2026" / "Mar 2026"
+    const my = sentence.match(/\b([A-Za-z]+)\s+(\d{4})\b/);
+    if (my) {
+        const m = MONTHS[my[1].toLowerCase()];
+        const y = Number(my[2]);
+        if (m && validYear(y)) {
+            return { occurredAt: isoMonth(y, m), matched: my[0], form: "my" };
+        }
+    }
+    // 4 + 5. "in YYYY" / "since YYYY"
+    const inYear = sentence.match(/\b(?:in|since)\s+(\d{4})\b/i);
+    if (inYear) {
+        const y = Number(inYear[1]);
+        if (validYear(y)) {
+            return { occurredAt: isoYear(y), matched: inYear[0], form: "in-year" };
+        }
+    }
+    // 6. Relative + quarter forms (Task 390). Delegated to the shared lib so the
+    // datetime skill calls the same code path. Checked before bare-year so that
+    // "Q3 2024" parses as the quarter rather than the bare year 2024.
+    const rel = parseRelativeDate(sentence, reference);
+    if (rel) {
+        return {
+            occurredAt: rel.date.toISOString().replace(/\.\d{3}Z$/, "Z"),
+            matched: rel.matched,
+            form: rel.form === "quarter" ? "quarter" : "relative",
+        };
+    }
+    // 7. Bare year — restrictive: must be 4 digits surrounded by word boundaries
+    // and not preceded by "$" (price), ":" (time), or "-" (already part of a
+    // date we would have matched above). Cheap defensive guards.
+    const bareYear = sentence.match(/(?<![$:\d-])\b(\d{4})\b(?!\s*[-/]\d)/);
+    if (bareYear) {
+        const y = Number(bareYear[1]);
+        if (validYear(y)) {
+            return { occurredAt: isoYear(y), matched: bareYear[0], form: "bare-year" };
+        }
+    }
+    return null;
+}
+/**
+ * Extract every dated statement from `body`. One row per sentence containing
+ * the first parseable date in that sentence. Sentences without a date are
+ * dropped silently (the diagnostic count is the caller's concern).
+ *
+ * `reference` anchors relative forms ("yesterday", "two weeks ago", "Q3 last
+ * year"). Callers pass the message's createdAt; absent that, current time.
+ */
+export function extractDatedStatements(body, reference = new Date()) {
+    if (!body || typeof body !== "string")
+        return [];
+    const ref = reference instanceof Date && !Number.isNaN(reference.getTime())
+        ? reference
+        : new Date();
+    const out = [];
+    const formCounts = {};
+    for (const sentence of splitSentences(body)) {
+        const hit = parseFirstDate(sentence, ref);
+        if (hit) {
+            out.push({
+                occurredAt: hit.occurredAt,
+                summary: clampSummary(sentence),
+                matched: hit.matched,
+                form: hit.form,
+            });
+            formCounts[hit.form] = (formCounts[hit.form] ?? 0) + 1;
+        }
+    }
+    // Task 390 diagnostic: coverage so the rewriter team can observe parse rate.
+    const forms = Object.keys(formCounts).sort().join(",");
+    // eslint-disable-next-line no-console
+    console.log(`[timeline-extract] coverage body-len=${body.length} dates=${out.length}${forms ? ` forms=[${forms}]` : ""}`);
+    return out;
+}
+//# sourceMappingURL=timeline-extractor.js.map