attraverso 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/server.js CHANGED
@@ -8,7 +8,7 @@ import { appendFile, mkdir, readFile, readdir, rename, rm, stat, writeFile } fro
8
8
  import { existsSync, readdirSync, watch } from "node:fs";
9
9
  import { homedir } from "node:os";
10
10
  import { createServer } from "node:http";
11
- import { spawn } from "node:child_process";
11
+ import { execFile, spawn } from "node:child_process";
12
12
  // \0rolldown/runtime.js
13
13
  var __create = Object.create;
14
14
  var __defProp = Object.defineProperty;
@@ -21963,7 +21963,7 @@ var StdioServerTransport = class {
21963
21963
  };
21964
21964
  // package.json
21965
21965
  var name = "attraverso";
21966
- var version$1 = "0.6.0";
21966
+ var version$1 = "0.7.0";
21967
21967
  var description = "Durable, structured project memory that Claude reads and writes over MCP, stored as version-controlled YAML.";
21968
21968
  var license = "Apache-2.0";
21969
21969
  var repository = {
@@ -27562,6 +27562,7 @@ var schema_exports = /* @__PURE__ */ __exportAll({
27562
27562
  projectNext: () => projectNext,
27563
27563
  projects: () => projects,
27564
27564
  scopedDependencies: () => scopedDependencies,
27565
+ sourceReferences: () => sourceReferences,
27565
27566
  users: () => users
27566
27567
  });
27567
27568
  /**
@@ -27844,6 +27845,41 @@ var layoutPositions = pgTable("layout_positions", {
27844
27845
  x: integer("x").notNull(),
27845
27846
  y: integer("y").notNull()
27846
27847
  }, (t) => [primaryKey({ columns: [t.projectId, t.node] })]);
27848
+ /**
27849
+ * Source references (`CTX-13`): where a claim in some prose came from. The text carries a pointer after the claim,
27850
+ * `[ref r7k2]`, and this table carries everything else - one row per *source*, the rows sharing a `key` making one
27851
+ * reference, so a claim gathers sources over time ("elevated whenever it has additional sources") without a
27852
+ * second table holding what they share. Text with no pointer is the agent's own reasoning, and has no row.
27853
+ *
27854
+ * - **The owner is an item or a context section**, exactly one, by foreign key, so deleting either cascades its
27855
+ * references away. Repeated on each of a reference's rows, and kept to one owner per key by the trigger rather
27856
+ * than an index, since several rows share a key.
27857
+ * - **`quoted_text` is the text this source vouched for when it was added**: a record of a moment, like an event
27858
+ * payload, never kept in sync, and how "text changed since" is told without storing a flag.
27859
+ * - **`source` is an open vocabulary**, like every other one here (`user`, `test`, `search`, `docs` today), validated
27860
+ * by the domain layer rather than a database enum.
27861
+ * - **Retired, never deleted**, so what a claim was once backed by stays legible.
27862
+ *
27863
+ * Not `references`: that is a reserved word in SQL.
27864
+ */
27865
+ var sourceReferences = pgTable("source_references", {
27866
+ id: text$1("id").primaryKey().$defaultFn(uuidv7),
27867
+ projectId: text$1("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }),
27868
+ key: text$1("key").notNull(),
27869
+ itemId: text$1("item_id").references(() => items.id, { onDelete: "cascade" }),
27870
+ sectionId: text$1("section_id").references(() => contextSections.id, { onDelete: "cascade" }),
27871
+ source: text$1("source").notNull(),
27872
+ detail: text$1("detail").notNull(),
27873
+ quotedText: text$1("quoted_text").notNull(),
27874
+ actor: text$1("actor").notNull(),
27875
+ recordedAt: text$1("recorded_at").notNull().$defaultFn(timestamp),
27876
+ retiredAt: text$1("retired_at")
27877
+ }, (t) => [
27878
+ check("source_references_one_owner", sql`(${t.itemId} IS NULL) <> (${t.sectionId} IS NULL)`),
27879
+ index("source_references_project_key").on(t.projectId, t.key),
27880
+ index("source_references_item").on(t.itemId),
27881
+ index("source_references_section").on(t.sectionId)
27882
+ ]);
27847
27883
  var events = pgTable("events", {
27848
27884
  id: text$1("id").primaryKey().$defaultFn(uuidv7),
27849
27885
  projectId: text$1("project_id").references(() => projects.id, { onDelete: "cascade" }),
@@ -42866,6 +42902,8 @@ var _0013_kind_bloodscream_default = "CREATE TABLE \"scoped_dependencies\" (\n \
42866
42902
  var _0014_past_chronomancer_default = "ALTER TABLE \"items\" ADD COLUMN \"start_on\" text;--> statement-breakpoint\nALTER TABLE \"items\" ADD COLUMN \"due_on\" text;--> statement-breakpoint\nCREATE INDEX \"items_project_due\" ON \"items\" USING btree (\"project_id\",\"due_on\");";
42867
42903
  // src/db/migrations/0015_stormy_blindfold.sql?raw
42868
42904
  var _0015_stormy_blindfold_default = "CREATE TABLE \"layout_positions\" (\n \"project_id\" text NOT NULL,\n \"node\" text NOT NULL,\n \"x\" integer NOT NULL,\n \"y\" integer NOT NULL,\n CONSTRAINT \"layout_positions_project_id_node_pk\" PRIMARY KEY(\"project_id\",\"node\")\n);\n--> statement-breakpoint\nALTER TABLE \"layout_positions\" ADD CONSTRAINT \"layout_positions_project_id_projects_id_fk\" FOREIGN KEY (\"project_id\") REFERENCES \"public\".\"projects\"(\"id\") ON DELETE cascade ON UPDATE no action;";
42905
+ // src/db/migrations/0016_brave_squadron_sinister.sql?raw
42906
+ var _0016_brave_squadron_sinister_default = "CREATE TABLE \"source_references\" (\n \"id\" text PRIMARY KEY NOT NULL,\n \"project_id\" text NOT NULL,\n \"key\" text NOT NULL,\n \"item_id\" text,\n \"section_id\" text,\n \"source\" text NOT NULL,\n \"detail\" text NOT NULL,\n \"quoted_text\" text NOT NULL,\n \"actor\" text NOT NULL,\n \"recorded_at\" text NOT NULL,\n \"retired_at\" text,\n CONSTRAINT \"source_references_one_owner\" CHECK ((\"source_references\".\"item_id\" IS NULL) <> (\"source_references\".\"section_id\" IS NULL))\n);\n--> statement-breakpoint\nALTER TABLE \"source_references\" ADD CONSTRAINT \"source_references_project_id_projects_id_fk\" FOREIGN KEY (\"project_id\") REFERENCES \"public\".\"projects\"(\"id\") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint\nALTER TABLE \"source_references\" ADD CONSTRAINT \"source_references_item_id_items_id_fk\" FOREIGN KEY (\"item_id\") REFERENCES \"public\".\"items\"(\"id\") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint\nALTER TABLE \"source_references\" ADD CONSTRAINT \"source_references_section_id_context_sections_id_fk\" FOREIGN KEY (\"section_id\") REFERENCES \"public\".\"context_sections\"(\"id\") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint\nCREATE INDEX \"source_references_project_key\" ON \"source_references\" USING btree (\"project_id\",\"key\");--> statement-breakpoint\nCREATE INDEX \"source_references_item\" ON \"source_references\" USING btree (\"item_id\");--> statement-breakpoint\nCREATE INDEX \"source_references_section\" ON \"source_references\" USING btree (\"section_id\");--> statement-breakpoint\n-- CTX-13: every live source reference's pointer is in its owner's text, and a key has one owner. Hand-written: a\n-- trigger is beyond what drizzle-kit generates. Deferred to commit, so a reference and its pointer can arrive in\n-- either order within one transaction. Each firing checks only the item, section or key that changed. Loading a\n-- plan file sets attraverso.loading_plan for its transaction and is let through: a hand edit that broke a\n-- pointer must still load (stale is a state a plan loads in, never a refusal to load), and apm:check reports it.\n-- A pointer is \"[ref key]\" or the expanded \"[ref key: ...]\", matched exactly so r7k2 never matches r7k29.\nCREATE FUNCTION \"source_references_check\"() RETURNS trigger LANGUAGE plpgsql AS $$\nDECLARE\n bad text;\nBEGIN\n IF current_setting('attraverso.loading_plan', true) = 'on' THEN\n RETURN NULL;\n END IF;\n IF TG_TABLE_NAME = 'items' THEN\n SELECT r.key INTO bad FROM source_references r JOIN items i ON i.id = r.item_id\n WHERE r.item_id = NEW.id AND r.retired_at IS NULL\n AND position('[ref ' || r.key || ']' IN coalesce(i.body, '')) = 0\n AND position('[ref ' || r.key || ':' IN coalesce(i.body, '')) = 0\n LIMIT 1;\n ELSIF TG_TABLE_NAME = 'context_sections' THEN\n SELECT r.key INTO bad FROM source_references r JOIN context_sections c ON c.id = r.section_id\n WHERE r.section_id = NEW.id AND r.retired_at IS NULL\n AND position('[ref ' || r.key || ']' IN c.content) = 0\n AND position('[ref ' || r.key || ':' IN c.content) = 0\n LIMIT 1;\n ELSE\n SELECT r.key INTO bad FROM source_references r\n LEFT JOIN items i ON i.id = r.item_id LEFT JOIN context_sections c ON c.id = r.section_id\n WHERE r.project_id = NEW.project_id AND r.key = NEW.key AND r.retired_at IS NULL\n AND position('[ref ' || r.key || ']' IN coalesce(i.body, c.content, '')) = 0\n AND position('[ref ' || r.key || ':' IN coalesce(i.body, c.content, '')) = 0\n LIMIT 1;\n IF bad IS NULL THEN\n SELECT r.key INTO bad FROM source_references r\n WHERE r.project_id = NEW.project_id AND r.key = NEW.key AND r.retired_at IS NULL\n GROUP BY r.key HAVING count(DISTINCT coalesce(r.item_id, r.section_id)) > 1;\n IF bad IS NOT NULL THEN\n RAISE EXCEPTION 'source reference % has more than one owner', bad USING ERRCODE = 'check_violation';\n END IF;\n END IF;\n END IF;\n IF bad IS NOT NULL THEN\n RAISE EXCEPTION 'source reference % is live but its pointer is not in the text', bad USING ERRCODE = 'check_violation';\n END IF;\n RETURN NULL;\nEND\n$$;\n--> statement-breakpoint\nCREATE CONSTRAINT TRIGGER \"source_references_on_items\" AFTER UPDATE OF \"body\" ON \"items\"\n DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION \"source_references_check\"();\n--> statement-breakpoint\nCREATE CONSTRAINT TRIGGER \"source_references_on_sections\" AFTER UPDATE OF \"content\" ON \"context_sections\"\n DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION \"source_references_check\"();\n--> statement-breakpoint\nCREATE CONSTRAINT TRIGGER \"source_references_on_rows\" AFTER INSERT OR UPDATE ON \"source_references\"\n DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION \"source_references_check\"();\n";
42869
42907
  // src/db/migrations/meta/_journal.json
42870
42908
  var version = "7";
42871
42909
  var dialect = "postgresql";
@@ -42981,6 +43019,13 @@ var entries = [
42981
43019
  "when": 1794545387434,
42982
43020
  "tag": "0015_stormy_blindfold",
42983
43021
  "breakpoints": true
43022
+ },
43023
+ {
43024
+ "idx": 16,
43025
+ "version": "7",
43026
+ "when": 1794774084272,
43027
+ "tag": "0016_brave_squadron_sinister",
43028
+ "breakpoints": true
42984
43029
  }
42985
43030
  ];
42986
43031
  var _journal_default = {
@@ -43006,7 +43051,8 @@ var files = /* #__PURE__ */ Object.assign({
43006
43051
  "./migrations/0012_smiling_butterfly.sql": _0012_smiling_butterfly_default,
43007
43052
  "./migrations/0013_kind_bloodscream.sql": _0013_kind_bloodscream_default,
43008
43053
  "./migrations/0014_past_chronomancer.sql": _0014_past_chronomancer_default,
43009
- "./migrations/0015_stormy_blindfold.sql": _0015_stormy_blindfold_default
43054
+ "./migrations/0015_stormy_blindfold.sql": _0015_stormy_blindfold_default,
43055
+ "./migrations/0016_brave_squadron_sinister.sql": _0016_brave_squadron_sinister_default
43010
43056
  });
43011
43057
  /** The breakpoint drizzle-kit writes between statements, and that drizzle's reader splits on. */
43012
43058
  var BREAKPOINT = "--> statement-breakpoint";
@@ -43126,6 +43172,12 @@ var dataDirFor = (storePath) => join(storePath, "..", isLegacyStore(storePath) ?
43126
43172
  * because positions change on every drag and every new item, and the plan file is the one a reviewer reads.
43127
43173
  */
43128
43174
  var layoutPathFor = (storePath) => join(dataDirFor(storePath), "layout.yaml");
43175
+ /**
43176
+ * Where a plan's source references live (`CTX-13`): beside it in its data folder, like its layout, because a source
43177
+ * carries a verbatim quote or a URL and a copy of the claim it vouched for - bulk a reader of the plan never reads,
43178
+ * and which would bury the items in it. Unlike the layout it is real data, so a save guards it like the plan.
43179
+ */
43180
+ var referencesPathFor = (storePath) => join(dataDirFor(storePath), "references.yaml");
43129
43181
  // src/domain/measurements.ts
43130
43182
  /**
43131
43183
  * Recording and querying measurements (`METRIC-2`).
@@ -50228,8 +50280,10 @@ async function clearAll(tx, { keepIdentity }) {
50228
50280
  * `priority` is a global integer that cannot be maintained across 157 items, and `status` says "committed or
50229
50281
  * not" without saying in what order.
50230
50282
  *
50231
- * **Short by construction is the feature.** Five to ten refs forces "does this beat what is already at
50232
- * position three?", and that forced comparison is what produces an ordering at all.
50283
+ * **The ranking is the feature, not the length.** It was "five to ten refs" until `PROJ-13` (2026-11-14): the
50284
+ * shortness was meant to force "does this beat what is already third?". The board (`VIEW-46`) made a longer
50285
+ * list readable, so the length advice went; what still forces the comparison is that the list is one ordered
50286
+ * list per project, replaced whole, most important first.
50233
50287
  *
50234
50288
  * Two rules here are worth stating because neither is obvious:
50235
50289
  *
@@ -50500,6 +50554,23 @@ var attachmentSchema = object({
50500
50554
  at: string(),
50501
50555
  actor: string()
50502
50556
  });
50557
+ /**
50558
+ * One source behind a source reference (`CTX-13`). References are written where their pointer is - under the item
50559
+ * whose body holds it, keyed by the pointer's key - so reading the file shows a claim's sources beside the item,
50560
+ * as comments are. The row's `id` rides along like a comment's, so a round trip keeps it and an edit can address it.
50561
+ * `text` is the exact text this source vouched for; `retired` is set when its pointer was removed.
50562
+ */
50563
+ var referenceSchema = object({
50564
+ source: string(),
50565
+ detail: string(),
50566
+ text: string(),
50567
+ id: string(),
50568
+ at: string(),
50569
+ actor: string(),
50570
+ retired: string().optional()
50571
+ });
50572
+ /** Pointer key -> its sources, oldest first. */
50573
+ var referencesSchema = record(string().regex(/^[a-z0-9]+$/, "a reference key is lowercase letters and digits"), array(referenceSchema));
50503
50574
  /** One project's layout: node id -> "x,y", whole numbers on the layout's grid. */
50504
50575
  var layoutSchema = record(string(), string().regex(/^-?\d+,-?\d+$/, "a layout position is \"x,y\" in whole numbers"));
50505
50576
  var itemSchema = object({
@@ -50531,7 +50602,8 @@ var itemSchema = object({
50531
50602
  comments: array(commentSchema).optional(),
50532
50603
  /** Accepted for old plan files, never written: see `readComments` (CTX-2). */
50533
50604
  notes: array(commentSchema).optional(),
50534
- attachments: array(attachmentSchema).optional()
50605
+ attachments: array(attachmentSchema).optional(),
50606
+ references: referencesSchema.optional()
50535
50607
  });
50536
50608
  var retiredSessionSchema = array(unknown());
50537
50609
  var projectSchema = object({
@@ -50546,6 +50618,7 @@ var projectSchema = object({
50546
50618
  updated_at: string(),
50547
50619
  archived_at: string().optional(),
50548
50620
  context: record(string(), string()).optional(),
50621
+ context_references: record(string(), referencesSchema).optional(),
50549
50622
  areas: array(areaSchema),
50550
50623
  items: array(itemSchema),
50551
50624
  sessions: retiredSessionSchema.optional(),
@@ -50603,7 +50676,7 @@ function asPlan(store) {
50603
50676
  return {
50604
50677
  ...rest,
50605
50678
  next: project.next?.filter((ref) => actionable.has(ref)),
50606
- items: live.map(({ body: _body, comments: _comments, notes: _notes, attachments: _attachments, ...item }) => ({
50679
+ items: live.map(({ body: _body, comments: _comments, notes: _notes, attachments: _attachments, references: _references, ...item }) => ({
50607
50680
  ...item,
50608
50681
  deps: item.deps?.filter((ref) => splitScope(ref) !== null || present.has(ref)),
50609
50682
  parent: item.parent !== void 0 && present.has(item.parent) ? item.parent : void 0
@@ -50665,6 +50738,28 @@ async function exportStore(db, ownerId) {
50665
50738
  actor: a.actor
50666
50739
  })) : void 0;
50667
50740
  const layoutRows = await db.select().from(layoutPositions).where(eq(layoutPositions.projectId, p.id)).orderBy(asc(layoutPositions.node));
50741
+ const referenceRows = await db.select().from(sourceReferences).where(eq(sourceReferences.projectId, p.id)).orderBy(asc(sourceReferences.key), asc(sourceReferences.recordedAt), asc(sourceReferences.id));
50742
+ const sectionHeading = new Map(sectionRows.map((s) => [s.id, s.heading]));
50743
+ const referencesByItem = /* @__PURE__ */ new Map();
50744
+ const referencesBySection = /* @__PURE__ */ new Map();
50745
+ for (const r of referenceRows) {
50746
+ const [owners, owner] = r.itemId !== null ? [referencesByItem, r.itemId] : [referencesBySection, sectionHeading.get(r.sectionId)];
50747
+ const byKey = owners.get(owner) ?? owners.set(owner, {}).get(owner);
50748
+ (byKey[r.key] ??= []).push({
50749
+ source: r.source,
50750
+ detail: r.detail,
50751
+ text: r.quotedText,
50752
+ id: r.id,
50753
+ at: r.recordedAt,
50754
+ actor: r.actor,
50755
+ retired: opt(r.retiredAt)
50756
+ });
50757
+ }
50758
+ const contextReferences = {};
50759
+ for (const s of sectionRows) {
50760
+ const refs = referencesBySection.get(s.heading);
50761
+ if (refs !== void 0) contextReferences[s.heading] = refs;
50762
+ }
50668
50763
  const fmtComments = (rows) => rows.length > 0 ? rows.map((n) => ({
50669
50764
  body: n.body,
50670
50765
  audience: n.audience,
@@ -50684,6 +50779,7 @@ async function exportStore(db, ownerId) {
50684
50779
  updated_at: p.updatedAt,
50685
50780
  archived_at: opt(p.archivedAt),
50686
50781
  context: sectionRows.length > 0 ? context : void 0,
50782
+ context_references: Object.keys(contextReferences).length > 0 ? contextReferences : void 0,
50687
50783
  comments: fmtComments(projectComments),
50688
50784
  attachments: fmtAttachments(projectAttachments),
50689
50785
  areas: areaRows.map((a) => ({
@@ -50714,7 +50810,8 @@ async function exportStore(db, ownerId) {
50714
50810
  closed_at: opt(i.closedAt),
50715
50811
  deleted_at: opt(i.deletedAt),
50716
50812
  comments: fmtComments(commentsByItem.get(i.id) ?? []),
50717
- attachments: fmtAttachments(attachmentsByItem.get(i.id) ?? [])
50813
+ attachments: fmtAttachments(attachmentsByItem.get(i.id) ?? []),
50814
+ references: referencesByItem.get(i.id)
50718
50815
  };
50719
50816
  }),
50720
50817
  layout: layoutRows.length > 0 ? Object.fromEntries(layoutRows.map((row) => [row.node, `${row.x},${row.y}`])) : void 0
@@ -50742,6 +50839,7 @@ async function replaceStore(db, store) {
50742
50839
  });
50743
50840
  }
50744
50841
  async function insertStore(tx, store, owner) {
50842
+ await tx.execute(sql`select set_config('attraverso.loading_plan', 'on', true)`);
50745
50843
  const ownerId = owner ?? (await ensureUserIn(tx, LOCAL_IDENTITY)).id;
50746
50844
  for (const p of store.projects) {
50747
50845
  await tx.insert(projects).values({
@@ -50830,12 +50928,43 @@ async function insertStore(tx, store, owner) {
50830
50928
  });
50831
50929
  if (layoutValues.length > 0) await tx.insert(layoutPositions).values(layoutValues);
50832
50930
  const contextEntries = Object.entries(p.context ?? {});
50833
- if (contextEntries.length > 0) await tx.insert(contextSections).values(contextEntries.map(([heading, content], index) => ({
50931
+ const headingToId = /* @__PURE__ */ new Map();
50932
+ if (contextEntries.length > 0) {
50933
+ const inserted = await tx.insert(contextSections).values(contextEntries.map(([heading, content], index) => ({
50934
+ projectId: p.id,
50935
+ heading,
50936
+ content,
50937
+ sortOrder: index
50938
+ }))).returning({
50939
+ id: contextSections.id,
50940
+ heading: contextSections.heading
50941
+ });
50942
+ for (const row of inserted) headingToId.set(row.heading, row.id);
50943
+ }
50944
+ const referenceValues = [...p.items.flatMap((i) => Object.entries(i.references ?? {}).map(([key, rows]) => ({
50945
+ key,
50946
+ rows,
50947
+ itemId: refToId.get(i.ref) ?? null,
50948
+ sectionId: null
50949
+ }))), ...Object.entries(p.context_references ?? {}).flatMap(([heading, refs]) => Object.entries(refs).map(([key, rows]) => ({
50950
+ key,
50951
+ rows,
50952
+ itemId: null,
50953
+ sectionId: headingToId.get(heading) ?? null
50954
+ })))].flatMap(({ key, rows, itemId, sectionId }) => itemId === null && sectionId === null ? [] : rows.map((r) => ({
50955
+ id: r.id,
50834
50956
  projectId: p.id,
50835
- heading,
50836
- content,
50837
- sortOrder: index
50957
+ key,
50958
+ itemId,
50959
+ sectionId,
50960
+ source: r.source,
50961
+ detail: r.detail,
50962
+ quotedText: r.text,
50963
+ actor: r.actor,
50964
+ recordedAt: r.at,
50965
+ retiredAt: r.retired ?? null
50838
50966
  })));
50967
+ if (referenceValues.length > 0) await tx.insert(sourceReferences).values(referenceValues);
50839
50968
  const commentValues = [...readComments(p).map((c) => ({
50840
50969
  comment: c,
50841
50970
  itemId: null
@@ -50909,6 +51038,67 @@ var stringifyLayout = (layouts) => (0, import_dist.stringify)(layouts, YAML_FORM
50909
51038
  function parseLayout(text) {
50910
51039
  return layoutFileSchema.parse((0, import_dist.parse)(text) ?? {});
50911
51040
  }
51041
+ /**
51042
+ * A plan's source references (`CTX-13`), kept in their own file beside it (`references.yaml`): per project key, its
51043
+ * items' references by ref and its context sections' by heading, each a pointer key to its sources. Keyed the way
51044
+ * the plan names things, by key, ref and heading, so the file reads beside the plan it explains.
51045
+ */
51046
+ var referencesFileSchema = record(string(), object({
51047
+ items: record(string(), referencesSchema).optional(),
51048
+ context: record(string(), referencesSchema).optional()
51049
+ }));
51050
+ /** A plan, with its source references taken out to be written to their own file. Everything else stays as it was. */
51051
+ function splitReferences(store) {
51052
+ const references = {};
51053
+ return {
51054
+ plan: { projects: store.projects.map(({ context_references, ...project }) => {
51055
+ const items = {};
51056
+ const stripped = project.items.map(({ references: refs, ...item }) => {
51057
+ if (refs !== void 0) items[item.ref] = refs;
51058
+ return item;
51059
+ });
51060
+ const entry = {
51061
+ ...Object.keys(items).length > 0 ? { items } : {},
51062
+ ...context_references !== void 0 ? { context: context_references } : {}
51063
+ };
51064
+ if (Object.keys(entry).length > 0) references[project.key] = entry;
51065
+ return {
51066
+ ...project,
51067
+ items: stripped
51068
+ };
51069
+ }) },
51070
+ references
51071
+ };
51072
+ }
51073
+ /**
51074
+ * Put a references file's sources back into the plan they belong to. **The file wins** for a project it names, over
51075
+ * references still inline in the plan (a plan saved before they had a file of their own), since every save since
51076
+ * has gone to the file; a project it does not name keeps what it had, so an inline plan loads, and its next save
51077
+ * moves them out. An entry naming an item or a heading the plan does not have is left out here and reported by
51078
+ * `apm:check` (`orphanedReferences`), rather than refusing the load.
51079
+ */
51080
+ var mergeReferences = (store, references) => ({ projects: store.projects.map((project) => {
51081
+ const entry = references[project.key];
51082
+ if (entry === void 0) return project;
51083
+ const items = project.items.map(({ references: _inline, ...item }) => {
51084
+ const refs = entry.items?.[item.ref];
51085
+ return refs === void 0 ? item : {
51086
+ ...item,
51087
+ references: refs
51088
+ };
51089
+ });
51090
+ const context = Object.fromEntries(Object.entries(entry.context ?? {}).filter(([heading]) => heading in (project.context ?? {})));
51091
+ return {
51092
+ ...project,
51093
+ items,
51094
+ context_references: Object.keys(context).length > 0 ? context : void 0
51095
+ };
51096
+ }) });
51097
+ var stringifyReferences = (references) => (0, import_dist.stringify)(references, YAML_FORMAT);
51098
+ /** A references file's contents. An empty file is no references. */
51099
+ function parseReferences(text) {
51100
+ return referencesFileSchema.parse((0, import_dist.parse)(text) ?? {});
51101
+ }
50912
51102
  function parseStore(text) {
50913
51103
  return storeSchema.parse((0, import_dist.parse)(text));
50914
51104
  }
@@ -51088,10 +51278,10 @@ async function writeAtomic(path, text) {
51088
51278
  */
51089
51279
  async function saveStore(db, path, only) {
51090
51280
  const { id: ownerId } = await ensureUser(db, LOCAL_IDENTITY);
51091
- const { plan, layouts } = splitLayout(restrict(await exportStore(db, ownerId), only));
51281
+ const { plan, sides } = splitSides(restrict(await exportStore(db, ownerId), only));
51092
51282
  const text = stringifyStore(plan);
51283
+ for (const kind of SIDE_KINDS) if (!kind.empty(sides.get(kind))) await writeAtomic(kind.pathFor(path), kind.stringify(sides.get(kind)));
51093
51284
  await writeAtomic(path, text);
51094
- if (Object.keys(layouts).length > 0) await writeAtomic(layoutPathFor(path), stringifyLayout(layouts));
51095
51285
  return hashOf$1(text);
51096
51286
  }
51097
51287
  /** The store narrowed to some project ids, preserving `exportStore`'s order so the result stays deterministic. */
@@ -51121,11 +51311,61 @@ async function stampOf(path) {
51121
51311
  return null;
51122
51312
  }
51123
51313
  }
51314
+ var LAYOUT = {
51315
+ name: "layout",
51316
+ pathFor: layoutPathFor,
51317
+ guarded: false,
51318
+ parse: parseLayout,
51319
+ stringify: (side) => stringifyLayout(side),
51320
+ split: (store) => {
51321
+ const { plan, layouts } = splitLayout(store);
51322
+ return {
51323
+ plan,
51324
+ side: layouts
51325
+ };
51326
+ },
51327
+ merge: (store, side) => mergeLayout(store, side),
51328
+ empty: (side) => Object.keys(side).length === 0
51329
+ };
51330
+ var REFERENCES = {
51331
+ name: "references",
51332
+ pathFor: referencesPathFor,
51333
+ guarded: true,
51334
+ parse: parseReferences,
51335
+ stringify: (side) => stringifyReferences(side),
51336
+ split: (store) => {
51337
+ const { plan, references } = splitReferences(store);
51338
+ return {
51339
+ plan,
51340
+ side: references
51341
+ };
51342
+ },
51343
+ merge: (store, side) => mergeReferences(store, side),
51344
+ empty: (side) => Object.keys(side).length === 0
51345
+ };
51346
+ /** References first: `save` writes them before the plan, so a save cut short leaves sources whose pointers are not
51347
+ * written yet (loaded as they are, and retired, never lost, by the next edit) rather than pointers with nothing
51348
+ * behind them. */
51349
+ var SIDE_KINDS = [REFERENCES, LAYOUT];
51350
+ /** A plan with every side file's part taken out, and each part by kind. */
51351
+ function splitSides(store) {
51352
+ const sides = /* @__PURE__ */ new Map();
51353
+ let plan = store;
51354
+ for (const kind of SIDE_KINDS) {
51355
+ const split = kind.split(plan);
51356
+ plan = split.plan;
51357
+ sides.set(kind, split.side);
51358
+ }
51359
+ return {
51360
+ plan,
51361
+ sides
51362
+ };
51363
+ }
51124
51364
  /**
51125
- * A layout file as read from disk, or null when there is none. Parse failures throw, naming the file: a
51126
- * half-merged layout should fail as loudly as a half-merged plan rather than quietly dropping the map.
51365
+ * A side file as read from disk, or null when there is none. Parse failures throw, naming the file: a half-merged
51366
+ * layout or references file should fail as loudly as a half-merged plan rather than quietly dropping its part.
51127
51367
  */
51128
- async function readLayoutFile(path) {
51368
+ async function readSideFile(kind, path) {
51129
51369
  let text;
51130
51370
  try {
51131
51371
  text = await readFile(path, "utf8");
@@ -51134,12 +51374,12 @@ async function readLayoutFile(path) {
51134
51374
  }
51135
51375
  try {
51136
51376
  return {
51137
- layouts: parseLayout(text),
51377
+ side: kind.parse(text),
51138
51378
  hash: hashOf$1(text),
51139
51379
  stamp: await stampOf(path)
51140
51380
  };
51141
51381
  } catch (cause) {
51142
- throw new Error(`${path} is not a layout file: ${cause instanceof Error ? cause.message : String(cause)}`);
51382
+ throw new Error(`${path} is not a ${kind.name} file: ${cause instanceof Error ? cause.message : String(cause)}`);
51143
51383
  }
51144
51384
  }
51145
51385
  /**
@@ -51176,30 +51416,31 @@ function createStoreFile(where) {
51176
51416
  file.keys = new Set(store.projects.map((project) => project.key));
51177
51417
  };
51178
51418
  /**
51179
- * The layout files (`VIEW-23.2`), one per data folder, with the version this process last read or wrote. Keyed
51180
- * by path rather than hung off each plan file, because two plan files can share a data folder (legacy
51181
- * `*.apm.yaml` side by side share `.apm/`) and so share one layout file.
51419
+ * The side files (the layout, `VIEW-23.2`; the references, `CTX-13`), one of each kind per data folder, with the
51420
+ * version this process last read or wrote. Keyed by path rather than hung off each plan file, because two plan
51421
+ * files can share a data folder (legacy `*.apm.yaml` side by side share `.apm/`) and so share one of each.
51182
51422
  */
51183
- const layoutFiles = /* @__PURE__ */ new Map();
51184
- for (const file of files) {
51185
- const path = layoutPathFor(file.path);
51186
- const entry = layoutFiles.get(path) ?? {
51423
+ const sideFiles = /* @__PURE__ */ new Map();
51424
+ for (const kind of SIDE_KINDS) for (const file of files) {
51425
+ const path = kind.pathFor(file.path);
51426
+ const entry = sideFiles.get(path) ?? {
51427
+ kind,
51187
51428
  known: null,
51188
51429
  stamp: null,
51189
51430
  owners: []
51190
51431
  };
51191
51432
  entry.owners.push(file);
51192
- layoutFiles.set(path, entry);
51433
+ sideFiles.set(path, entry);
51193
51434
  }
51194
51435
  /**
51195
- * Read every layout file from disk and lay it over the plans it belongs to, recording what was read. Runs on
51196
- * open and on every rebuild, so the database's layout is always the files' - a branch switch that changes only
51197
- * the map reloads it like any other change.
51436
+ * Read every side file from disk and lay it over the plans it belongs to, recording what was read. Runs on open
51437
+ * and on every rebuild, so the database's layout and references are always the files' - a branch switch that
51438
+ * changes only the map, or only a source, reloads it like any other change.
51198
51439
  */
51199
- const overlayLayouts = async (loaded) => {
51440
+ const overlaySides = async (loaded) => {
51200
51441
  const out = [...loaded];
51201
- for (const [path, entry] of layoutFiles) {
51202
- const read = await readLayoutFile(path);
51442
+ for (const [path, entry] of sideFiles) {
51443
+ const read = await readSideFile(entry.kind, path);
51203
51444
  if (read === null) continue;
51204
51445
  entry.known = read.hash;
51205
51446
  entry.stamp = read.stamp;
@@ -51207,7 +51448,7 @@ function createStoreFile(where) {
51207
51448
  const one = out[index];
51208
51449
  if (entry.owners.includes(one.file)) out[index] = {
51209
51450
  file: one.file,
51210
- store: mergeLayout(one.store, read.layouts)
51451
+ store: entry.kind.merge(one.store, read.side)
51211
51452
  };
51212
51453
  }
51213
51454
  }
@@ -51286,7 +51527,7 @@ function createStoreFile(where) {
51286
51527
  store
51287
51528
  })));
51288
51529
  let created = false;
51289
- for (const { file, store } of await overlayLayouts(loaded)) {
51530
+ for (const { file, store } of await overlaySides(loaded)) {
51290
51531
  claim(file, store);
51291
51532
  await importStore(db, store);
51292
51533
  }
@@ -51322,18 +51563,18 @@ function createStoreFile(where) {
51322
51563
  stamp: current
51323
51564
  });
51324
51565
  }
51325
- let layoutMoved = false;
51326
- for (const [path, entry] of layoutFiles) {
51566
+ let sideMoved = false;
51567
+ for (const [path, entry] of sideFiles) {
51327
51568
  const current = await stampOf(path);
51328
51569
  if (current === null || current === entry.stamp) continue;
51329
51570
  if (await hashOnDisk(path) === entry.known) entry.stamp = current;
51330
- else layoutMoved = true;
51571
+ else sideMoved = true;
51331
51572
  }
51332
- if (fresh.size === 0 && !layoutMoved) return false;
51573
+ if (fresh.size === 0 && !sideMoved) return false;
51333
51574
  const { id: ownerId } = await ensureUser(db, LOCAL_IDENTITY);
51334
51575
  const loadedNow = await exportStore(db, ownerId);
51335
51576
  const claimed = new Set(files.flatMap((file) => [...file.ids]));
51336
- const union = await overlayLayouts(files.map((file) => {
51577
+ const union = await overlaySides(files.map((file) => {
51337
51578
  const moved = fresh.get(file);
51338
51579
  if (moved !== void 0) return {
51339
51580
  file,
@@ -51362,38 +51603,56 @@ function createStoreFile(where) {
51362
51603
  return true;
51363
51604
  }),
51364
51605
  save: (db) => exclusive(async () => {
51606
+ const refuse = (path, gone) => {
51607
+ throw new Error(`refusing to save: ${path} ${gone ? "has been deleted" : "has changed"} since this server loaded it, so writing would overwrite whatever changed it (another apm server, a git checkout, or a hand edit). This change was applied in memory but NOT saved. ` + (gone ? "Restore the file, or reconnect the apm server to start a fresh one, then make the change again." : "The next call reloads the file, which discards this change, so make it again after that."));
51608
+ };
51365
51609
  for (const file of files) {
51366
51610
  const current = await hashOnDisk(file.path);
51367
- if (file.known !== null && current !== file.known) {
51368
- const gone = current === null;
51369
- throw new Error(`refusing to save: ${file.path} ${gone ? "has been deleted" : "has changed"} since this server loaded it, so writing would overwrite whatever changed it (another apm server, a git checkout, or a hand edit). This change was applied in memory but NOT saved. ` + (gone ? "Restore the file, or reconnect the apm server to start a fresh one, then make the change again." : "The next call reloads the file, which discards this change, so make it again after that."));
51370
- }
51611
+ if (file.known !== null && current !== file.known) refuse(file.path, current === null);
51612
+ }
51613
+ for (const [path, entry] of sideFiles) {
51614
+ if (!entry.kind.guarded || entry.known === null) continue;
51615
+ const current = await hashOnDisk(path);
51616
+ if (current !== entry.known) refuse(path, current === null);
51371
51617
  }
51372
51618
  const { id: ownerId } = await ensureUser(db, LOCAL_IDENTITY);
51373
51619
  const full = await exportStore(db, ownerId);
51374
51620
  const claimed = new Set(files.flatMap((file) => [...file.ids]));
51375
- const layoutsOf = /* @__PURE__ */ new Map();
51621
+ const sidesOf = /* @__PURE__ */ new Map();
51622
+ const plans = [];
51376
51623
  for (const file of files) {
51377
51624
  const mine = full.projects.filter((p) => file.ids.has(p.id) || file === primary && !claimed.has(p.id));
51378
- const { plan, layouts } = splitLayout({ projects: mine });
51379
- layoutsOf.set(file, layouts);
51625
+ const { plan, sides } = splitSides({ projects: mine });
51626
+ sidesOf.set(file, sides);
51380
51627
  const text = stringifyStore(plan);
51381
- const hash = hashOf$1(text);
51628
+ plans.push({
51629
+ file,
51630
+ mine,
51631
+ text,
51632
+ hash: hashOf$1(text)
51633
+ });
51634
+ }
51635
+ const writeSides = async (kinds) => {
51636
+ for (const [path, entry] of sideFiles) {
51637
+ if (!kinds.includes(entry.kind)) continue;
51638
+ const side = Object.assign({}, ...entry.owners.map((owner) => sidesOf.get(owner)?.get(entry.kind) ?? {}));
51639
+ if (entry.kind.empty(side) && entry.known === null) continue;
51640
+ const text = entry.kind.stringify(side);
51641
+ const hash = hashOf$1(text);
51642
+ if (hash === entry.known) continue;
51643
+ await writeAtomic(path, text);
51644
+ entry.known = hash;
51645
+ entry.stamp = await stampOf(path);
51646
+ }
51647
+ };
51648
+ await writeSides([REFERENCES]);
51649
+ for (const { file, mine, text, hash } of plans) {
51382
51650
  if (hash === file.known) continue;
51383
51651
  await writeAtomic(file.path, text);
51384
51652
  claim(file, { projects: mine });
51385
51653
  await remember(file, hash);
51386
51654
  }
51387
- for (const [path, entry] of layoutFiles) {
51388
- const layouts = Object.assign({}, ...entry.owners.map((owner) => layoutsOf.get(owner) ?? {}));
51389
- if (Object.keys(layouts).length === 0 && entry.known === null) continue;
51390
- const text = stringifyLayout(layouts);
51391
- const hash = hashOf$1(text);
51392
- if (hash === entry.known) continue;
51393
- await writeAtomic(path, text);
51394
- entry.known = hash;
51395
- entry.stamp = await stampOf(path);
51396
- }
51655
+ await writeSides([LAYOUT]);
51397
51656
  })
51398
51657
  };
51399
51658
  }
@@ -51402,6 +51661,7 @@ var accessTo = (store, db) => ({
51402
51661
  refresh: () => store.refresh(db),
51403
51662
  reloads: () => store.reloads(),
51404
51663
  paths: () => store.paths,
51664
+ planFileOf: (key) => store.fileOf(key),
51405
51665
  appendMeasurements: (records) => store.appendMeasurements(records)
51406
51666
  });
51407
51667
  // src/media/store.ts
@@ -51504,6 +51764,468 @@ function createUnavailableMediaStore(reason) {
51504
51764
  }
51505
51765
  };
51506
51766
  }
51767
+ // scripts/references.ts
51768
+ /**
51769
+ * Source reference pointers in prose (`CTX-13`): where they are, and what text each one stands behind.
51770
+ *
51771
+ * A claim is followed by a pointer, `[ref r7k2]`, and the reference's sources live in `source_references`. This
51772
+ * module is the one parser every reader shares - the tools, `apm:check` and the viewer - so it is Node-free, like
51773
+ * `tickets.ts`: two parsers that split a body differently would make one claim stale in one place and fine in
51774
+ * another.
51775
+ *
51776
+ * **What a pointer covers is set by where it sits, never stored:**
51777
+ *
51778
+ * - **Inline, it covers the text before it** in the same markdown block, back to the previous pointer or the
51779
+ * block's start - the footnote convention, a citation after its claim. A block is a paragraph, one list item,
51780
+ * one table row, a heading, or a code block.
51781
+ * - **On its own line, it covers the whole group above it**: a paragraph, a whole list, a whole table, a code block.
51782
+ * Pointer-only lines in between are skipped, so two sources can stand behind one table.
51783
+ *
51784
+ * **What is not a pointer:** anything inside a code span or a fenced block, so documentation of this syntax never
51785
+ * trips it; an escaped `\[ref`; one followed by `(` or `:`, which markdown reads as a link or a link definition
51786
+ * (`[ref docs](https://...)`); and only `[ref ` followed by a key opens one, so task boxes and footnotes never do.
51787
+ * Indented code is not masked, deliberately: four-space list continuations are far commoner in these bodies.
51788
+ *
51789
+ * Deliberately a small line scanner rather than a markdown parser: the server has no markdown dependency at
51790
+ * runtime, and the few block shapes that matter here are easy to tell apart by their first characters.
51791
+ */
51792
+ /** A key is short lowercase letters and digits, generated by the tool: never shaped like an item's ref. */
51793
+ var KEY = "[a-z0-9]+";
51794
+ /** How long an expanded pointer's detail may run: `get_item` keeps what it shows well under it, and the bound keeps a
51795
+ * run of unclosed `[ref k:` from costing quadratic time on hostile input. */
51796
+ var EXPANSION = "[^\\]\\n]{0,3000}";
51797
+ /** `[ref key]`, or the expanded `[ref key: ...]` that `get_item` returns and an agent may send straight back. Not
51798
+ * escaped, and not followed by `(` or `:`, which would make it a link or a link definition. */
51799
+ var POINTER = new RegExp(`(?<!\\\\)\\[ref (${KEY})(?::${EXPANSION})?\\](?![(:])`, "g");
51800
+ /** `[ref ` not followed by a well-formed key and its close: a pointer someone meant to write and got wrong. */
51801
+ var MALFORMED = new RegExp(`(?<!\\\\)\\[ref (?!${KEY}(?:\\]|:${EXPANSION}\\]))`, "g");
51802
+ /**
51803
+ * The comparison form of some covered text: whitespace collapsed, Unicode NFC, and trimmed of what surrounds a
51804
+ * claim rather than belonging to it - a list marker or heading hashes in front, a table's pipes, the punctuation
51805
+ * left at the start of a span by the previous pointer's sentence.
51806
+ */
51807
+ function normaliseClaim(text) {
51808
+ return text.normalize("NFC").replace(/^[ \t]*>[ \t]?/gm, "").replace(/\s+/g, " ").replace(/^\s*(?:[-*+]|\d+[.)]|#{1,6})\s+/, "").replace(/^[\s|.,;:!?)]+/, "").replace(/[\s|]+$/, "").trim();
51809
+ }
51810
+ /** A fence marker opening a line: three or more backticks or tildes. */
51811
+ var fenceOf = (line) => /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
51812
+ /** Whether `marker` closes a block opened by `fence`: the same character, at least as many of it. */
51813
+ var closes = (fence, marker) => marker[0] === fence[0] && marker.length >= fence.length;
51814
+ /** The text with every code span and fenced block blanked to spaces, keeping offsets, so pointers in code vanish. */
51815
+ function maskCode(text) {
51816
+ const lines = text.split("\n");
51817
+ let fence;
51818
+ return lines.map((line) => {
51819
+ const marker = fenceOf(line);
51820
+ if (fence === void 0 && marker !== void 0) {
51821
+ fence = marker;
51822
+ return " ".repeat(line.length);
51823
+ }
51824
+ if (fence !== void 0) {
51825
+ if (marker !== void 0 && closes(fence, marker)) fence = void 0;
51826
+ return " ".repeat(line.length);
51827
+ }
51828
+ return line;
51829
+ }).join("\n").split(/(\n[ \t]*\n)/).map(maskSpans).join("");
51830
+ }
51831
+ /**
51832
+ * Blank the inline code spans in one paragraph: a run of backticks closed by the next run of exactly the same
51833
+ * length. A run with no partner is literal text, and the scan carries on after it, as CommonMark has it - so a
51834
+ * stray backtick in prose ("the ` key") hides nothing after it.
51835
+ */
51836
+ function maskSpans(paragraph) {
51837
+ const runs = [...paragraph.matchAll(/`+/g)].map((m) => ({
51838
+ at: m.index,
51839
+ length: m[0].length
51840
+ }));
51841
+ const nextSame = new Array(runs.length).fill(-1);
51842
+ const seen = /* @__PURE__ */ new Map();
51843
+ for (let i = runs.length - 1; i >= 0; i--) {
51844
+ nextSame[i] = seen.get(runs[i].length) ?? -1;
51845
+ seen.set(runs[i].length, i);
51846
+ }
51847
+ const pieces = [];
51848
+ let last = 0;
51849
+ for (let i = 0; i < runs.length; i++) {
51850
+ const open = runs[i];
51851
+ const close = nextSame[i];
51852
+ if (close === -1) continue;
51853
+ const end = runs[close].at + open.length;
51854
+ pieces.push(paragraph.slice(last, open.at), " ".repeat(end - open.at));
51855
+ last = end;
51856
+ i = close;
51857
+ }
51858
+ return last === 0 ? paragraph : pieces.join("") + paragraph.slice(last);
51859
+ }
51860
+ /**
51861
+ * Split a text into blocks by its lines, with offsets into the original text. A paragraph runs until a blank line
51862
+ * or a line that opens a block of its own; a list item takes the unmarked lines after it (its lazy continuation);
51863
+ * a heading and a table row are one line each; a fenced block runs to its closing fence. Consecutive list items
51864
+ * share a group, even across a blank line, as do consecutive table rows, which is what an own-line pointer covers.
51865
+ */
51866
+ function blocks(text) {
51867
+ const out = [];
51868
+ let group = 0;
51869
+ let offset = 0;
51870
+ let open = null;
51871
+ let fence;
51872
+ let afterBlank = false;
51873
+ for (const line of text.split("\n")) {
51874
+ const start = offset;
51875
+ const end = offset + line.length;
51876
+ offset = end + 1;
51877
+ const marker = fenceOf(line);
51878
+ if (fence !== void 0) {
51879
+ open.end = end;
51880
+ if (marker !== void 0 && closes(fence, marker)) {
51881
+ fence = void 0;
51882
+ open = null;
51883
+ }
51884
+ continue;
51885
+ }
51886
+ if (marker !== void 0) {
51887
+ fence = marker;
51888
+ open = {
51889
+ kind: "code",
51890
+ group: ++group,
51891
+ start,
51892
+ end
51893
+ };
51894
+ out.push(open);
51895
+ continue;
51896
+ }
51897
+ if (line.trim() === "") {
51898
+ open = null;
51899
+ afterBlank = true;
51900
+ continue;
51901
+ }
51902
+ const wasBlank = afterBlank;
51903
+ afterBlank = false;
51904
+ const kind = /^\s*#{1,6}\s/.test(line) ? "heading" : /^\s*\|/.test(line) ? "table" : /^\s*(?:[-*+]|\d+[.)])\s/.test(line) ? "list" : null;
51905
+ if (kind === null && open !== null && (open.kind === "paragraph" || open.kind === "list")) {
51906
+ open.end = end;
51907
+ continue;
51908
+ }
51909
+ const last = out[out.length - 1];
51910
+ const joins = kind !== null && last !== void 0 && last.kind === kind && (kind === "list" || !wasBlank);
51911
+ const block = {
51912
+ kind: kind ?? "paragraph",
51913
+ group: joins ? last.group : ++group,
51914
+ start,
51915
+ end
51916
+ };
51917
+ out.push(block);
51918
+ open = block.kind === "heading" || block.kind === "table" ? null : block;
51919
+ }
51920
+ return out;
51921
+ }
51922
+ /**
51923
+ * Every pointer in `text`, with what it covers, and every problem a writer should be told about: a malformed
51924
+ * pointer, the same key twice, and a pointer line directly under a table row, which markdown reads as another row
51925
+ * of the table rather than a pointer below it (the blank line nobody sees).
51926
+ */
51927
+ function parsePointers(text) {
51928
+ const cached = parsed.get(text);
51929
+ if (cached !== void 0) return cached;
51930
+ const result = Object.freeze(parseUncached(text));
51931
+ Object.freeze(result.pointers);
51932
+ Object.freeze(result.problems);
51933
+ parsed.set(text, result);
51934
+ if (parsed.size > PARSE_CACHE) parsed.delete(parsed.keys().next().value);
51935
+ return result;
51936
+ }
51937
+ /** How many texts' answers `parsePointers` keeps: enough for a write's before and after, its tool reply, and a
51938
+ * read or two in between, without holding on to a whole plan's bodies. Oldest out first. */
51939
+ var PARSE_CACHE = 16;
51940
+ var parsed = /* @__PURE__ */ new Map();
51941
+ function parseUncached(text) {
51942
+ const masked = maskCode(text);
51943
+ const all = blocks(text);
51944
+ const pointers = [];
51945
+ const problems = [];
51946
+ const seen = /* @__PURE__ */ new Set();
51947
+ for (const match of masked.matchAll(MALFORMED)) {
51948
+ const snippet = text.slice(match.index, match.index + 16).split("\n")[0];
51949
+ problems.push({
51950
+ at: match.index,
51951
+ problem: `"${snippet}" is not a pointer: write [ref <key>], where a key is lowercase letters and digits`
51952
+ });
51953
+ }
51954
+ /** The original text of [from, to) with its pointers taken out, normalised: what a pointer covers. Code stays
51955
+ * in, since a claim can be about a command; only pointers, found in the masked copy, are removed. */
51956
+ const covered = (from, to) => {
51957
+ let out = "";
51958
+ let last = from;
51959
+ for (const m of masked.slice(from, to).matchAll(POINTER)) {
51960
+ out += text.slice(last, from + m.index) + " ";
51961
+ last = from + m.index + m[0].length;
51962
+ }
51963
+ return normaliseClaim(out + text.slice(last, to));
51964
+ };
51965
+ all.forEach((block, index) => {
51966
+ const inBlock = [...masked.slice(block.start, block.end).matchAll(POINTER)].map((m) => ({
51967
+ key: m[1],
51968
+ at: block.start + m.index,
51969
+ written: m[0]
51970
+ }));
51971
+ if (inBlock.length === 0) return;
51972
+ if (normaliseClaim(masked.slice(block.start, block.end).replace(POINTER, " ")) === "") {
51973
+ const above = all.slice(0, index).reverse().find((candidate) => candidate.kind === "code" || normaliseClaim(masked.slice(candidate.start, candidate.end).replace(POINTER, " ")) !== "");
51974
+ if (above !== void 0 && above.kind === "table" && !/\n\s*\n/.test(text.slice(above.end, block.start))) problems.push({
51975
+ at: inBlock[0].at,
51976
+ problem: `put a blank line between the table and [ref ${inBlock[0].key}], or markdown reads it as another row`
51977
+ });
51978
+ const covers = (above === void 0 ? [] : all.filter((candidate) => candidate.group === above.group && candidate.end <= block.start)).map((b) => covered(b.start, b.end)).filter(Boolean).join(" ");
51979
+ for (const p of inBlock) pointers.push({
51980
+ ...p,
51981
+ covers: normaliseClaim(covers)
51982
+ });
51983
+ return;
51984
+ }
51985
+ let from = block.start;
51986
+ for (const p of inBlock) {
51987
+ const lineStart = text.lastIndexOf("\n", p.at - 1) + 1;
51988
+ const lineEnd = text.indexOf("\n", p.at) === -1 ? text.length : text.indexOf("\n", p.at);
51989
+ if (block.kind === "list" && lineStart > block.start && normaliseClaim(masked.slice(lineStart, lineEnd).replace(POINTER, " ")) === "") problems.push({
51990
+ at: p.at,
51991
+ problem: `put a blank line between the list and [ref ${p.key}], or markdown reads it as part of the last item`
51992
+ });
51993
+ pointers.push({
51994
+ ...p,
51995
+ covers: covered(from, p.at)
51996
+ });
51997
+ from = p.at + p.written.length;
51998
+ }
51999
+ });
52000
+ for (const p of pointers) if (p.covers === "") problems.push({
52001
+ at: p.at,
52002
+ problem: `[ref ${p.key}] has nothing before it to stand behind: put it straight after its claim`
52003
+ });
52004
+ for (const p of pointers) {
52005
+ if (seen.has(p.key)) problems.push({
52006
+ at: p.at,
52007
+ problem: `[ref ${p.key}] appears twice: a key stands behind one claim`
52008
+ });
52009
+ seen.add(p.key);
52010
+ }
52011
+ return {
52012
+ pointers,
52013
+ problems
52014
+ };
52015
+ }
52016
+ /** The text with every expanded pointer reduced to its bare form, `[ref key: ...]` to `[ref key]`, outside code -
52017
+ * what is stored, whatever `get_item` returned and the writer sent back. */
52018
+ function bareForm(text) {
52019
+ const masked = maskCode(text);
52020
+ let out = "";
52021
+ let last = 0;
52022
+ for (const match of masked.matchAll(POINTER)) {
52023
+ out += text.slice(last, match.index) + `[ref ${match[1]}]`;
52024
+ last = match.index + match[0].length;
52025
+ }
52026
+ return out + text.slice(last);
52027
+ }
52028
+ /**
52029
+ * `path:line[-line][:column]@commit`, e.g. `packages/core/src/domain/items.ts:308-339@345a746`. Repo-relative rather
52030
+ * than a hosting provider's URL, so it works in a private repo, a fork and the open export alike; a viewer can still
52031
+ * make a link of it where it knows the host. Null when the detail is not one, which the writing tool refuses.
52032
+ */
52033
+ function parseCodeRef(detail) {
52034
+ const match = /^([^\s:@][^\s:@]*):([1-9]\d*)(?:-([1-9]\d*))?(?::([1-9]\d*))?@([0-9a-f]{7,40})$/.exec(detail.trim());
52035
+ if (match === null) return null;
52036
+ if (match[1].startsWith("/") || match[1].includes("\\") || match[1].split("/").includes("..")) return null;
52037
+ const from = Number(match[2]);
52038
+ const to = match[3] === void 0 ? from : Number(match[3]);
52039
+ if (to < from) return null;
52040
+ return {
52041
+ path: match[1],
52042
+ from,
52043
+ to,
52044
+ ...match[4] === void 0 ? {} : { column: Number(match[4]) },
52045
+ commit: match[5]
52046
+ };
52047
+ }
52048
+ // src/domain/references.ts
52049
+ /**
52050
+ * Source references (`CTX-13`): where a claim in some prose came from.
52051
+ *
52052
+ * The text carries a pointer after the claim, `[ref r7k2]`, and `source_references` carries one row per source
52053
+ * behind it. Everything here is advisory - nothing a writer does to the prose is refused over a reference - except
52054
+ * the one rule the database itself enforces at commit: **a live reference's pointer is in its owner's text**, so a
52055
+ * pointer cannot vanish while its reference still claims to stand behind something. The domain keeps that rule
52056
+ * true for every tool write by retiring, in the same transaction, the references whose pointers an edit removed;
52057
+ * the trigger is the backstop for every other path.
52058
+ */
52059
+ /**
52060
+ * Retire every live reference of `owner` whose pointer `text` no longer carries, and say which keys they were.
52061
+ *
52062
+ * Called by every write that replaces an owner's prose, inside its transaction, so the commit-time check finds
52063
+ * nothing to object to. Retired rather than deleted: what a claim was once backed by stays legible, and the event
52064
+ * for the edit records which references went with it.
52065
+ */
52066
+ async function retireRemovedPointers(tx, owner, text) {
52067
+ const ownedBy = "itemId" in owner ? eq(sourceReferences.itemId, owner.itemId) : eq(sourceReferences.sectionId, owner.sectionId);
52068
+ const live = await tx.select({ key: sourceReferences.key }).from(sourceReferences).where(and(ownedBy, isNull(sourceReferences.retiredAt)));
52069
+ const pointed = new Set(parsePointers(text).pointers.map((p) => p.key));
52070
+ const gone = [...new Set(live.map((row) => row.key))].filter((key) => !pointed.has(key)).sort();
52071
+ if (gone.length === 0) return [];
52072
+ const now = timestamp();
52073
+ for (const key of gone) await tx.update(sourceReferences).set({ retiredAt: now }).where(and(ownedBy, eq(sourceReferences.key, key), isNull(sourceReferences.retiredAt)));
52074
+ return gone;
52075
+ }
52076
+ /** Where a claim's source can come from. `agent` is the default for anything unreferenced and is never written. */
52077
+ var SOURCE_KINDS = [
52078
+ "user",
52079
+ "test",
52080
+ "search",
52081
+ "docs",
52082
+ "code"
52083
+ ];
52084
+ /** A different advisory-lock namespace from ref allocation's, so the two never queue behind each other. */
52085
+ var REFERENCE_LOCK = 7172013;
52086
+ /**
52087
+ * Add sources to the references in `text`, after it has been written, inside the writing transaction.
52088
+ *
52089
+ * Each key must have its pointer in the text - the source stands behind *that* claim, and records the text it
52090
+ * covers now as what it vouched for - and must not be live under another owner. Serialised per project by an
52091
+ * advisory lock, because "one key, one owner" is a read-then-write: under READ COMMITTED two writers giving one
52092
+ * key to different items at once would both pass the check (found in the `CTX-13` spike, the same race `OPS-2`
52093
+ * fixed for ref allocation). The commit-time trigger would still refuse the second, but as a bare failure; the
52094
+ * lock turns it into a named one.
52095
+ */
52096
+ async function addSources(tx, projectId, owner, text, sources, actor) {
52097
+ const keys = Object.keys(sources);
52098
+ if (keys.length === 0) return [];
52099
+ await tx.execute(sql`SELECT pg_advisory_xact_lock(${REFERENCE_LOCK}, hashtext(${projectId}))`);
52100
+ const covers = new Map(parsePointers(text).pointers.map((p) => [p.key, p.covers]));
52101
+ const ownerId = "itemId" in owner ? owner.itemId : owner.sectionId;
52102
+ const rows = [];
52103
+ for (const key of keys) {
52104
+ const claim = covers.get(key);
52105
+ if (claim === void 0) throw new Error(`no [ref ${key}] in the text: write it straight after the claim it stands behind, as [ref ${key}]`);
52106
+ if (claim === "") throw new Error(`[ref ${key}] has no claim before it: put it straight after the sentence it stands behind`);
52107
+ if ((await tx.select({
52108
+ itemId: sourceReferences.itemId,
52109
+ sectionId: sourceReferences.sectionId
52110
+ }).from(sourceReferences).where(and(eq(sourceReferences.projectId, projectId), eq(sourceReferences.key, key), isNull(sourceReferences.retiredAt)))).some((row) => (row.itemId ?? row.sectionId) !== ownerId)) throw new Error(`reference ${key} already stands behind a claim elsewhere in this project: choose another key`);
52111
+ for (const source of [sources[key]].flat()) {
52112
+ if (!SOURCE_KINDS.includes(source.source)) throw new Error(`"${source.source}" is not a source: use one of ${SOURCE_KINDS.join(", ")} (unreferenced text is your own reasoning)`);
52113
+ if (source.detail.trim() === "") throw new Error(`a ${source.source} source needs its detail: the command, URL or file, or the user's words verbatim`);
52114
+ if (source.source === "code" && parseCodeRef(source.detail) === null) throw new Error(`"${source.detail}" is not a code reference: write path:line or path:from-to, optionally :column, then @commit, e.g. src/db/schema.ts:120-140@345a746`);
52115
+ rows.push({
52116
+ projectId,
52117
+ key,
52118
+ itemId: "itemId" in owner ? owner.itemId : null,
52119
+ sectionId: "sectionId" in owner ? owner.sectionId : null,
52120
+ source: source.source,
52121
+ detail: source.detail.trim(),
52122
+ quotedText: claim,
52123
+ actor
52124
+ });
52125
+ }
52126
+ }
52127
+ if (rows.length === 0) return [];
52128
+ await tx.insert(sourceReferences).values(rows);
52129
+ return rows.map((row) => ({
52130
+ key: row.key,
52131
+ source: row.source,
52132
+ detail: row.detail
52133
+ })).sort((a, b) => a.key.localeCompare(b.key));
52134
+ }
52135
+ /** The live sources behind an owner's references, oldest first within each key. */
52136
+ async function liveSources(db, owner) {
52137
+ const ownedBy = "itemId" in owner ? eq(sourceReferences.itemId, owner.itemId) : eq(sourceReferences.sectionId, owner.sectionId);
52138
+ return db.select({
52139
+ key: sourceReferences.key,
52140
+ source: sourceReferences.source,
52141
+ detail: sourceReferences.detail,
52142
+ quotedText: sourceReferences.quotedText,
52143
+ recordedAt: sourceReferences.recordedAt
52144
+ }).from(sourceReferences).where(and(ownedBy, isNull(sourceReferences.retiredAt))).orderBy(asc(sourceReferences.key), asc(sourceReferences.recordedAt), asc(sourceReferences.id));
52145
+ }
52146
+ /** A command, a file or a URL longer than this is left out of an expanded pointer: a cut one is noise. */
52147
+ var SHORT_DETAIL = 40;
52148
+ /** A user's words past this are cut, with an ellipsis, rather than dropped: the quote is the evidence. */
52149
+ var QUOTE_SHOWN = 100;
52150
+ /**
52151
+ * How much of a source's detail an expanded pointer shows by default, by kind (`CTX-16`). One length for all of
52152
+ * them hid what made a source useful: every `code` location (45 to 60 characters below `packages/`) and most of
52153
+ * the user's words, so a reader saw "code 2026-11-16" and not which file. So a code location always shows, being
52154
+ * short enough and the most checkable detail there is; a quote shows up to `QUOTE_SHOWN`, cut at a word; anything
52155
+ * else only when it fits whole. `references: "full"` shows every detail in full.
52156
+ */
52157
+ function detailShown(source, detail) {
52158
+ if (source === "code") return detail;
52159
+ if (source === "user") {
52160
+ if (detail.length <= QUOTE_SHOWN) return `"${detail}"`;
52161
+ const cut = detail.slice(0, QUOTE_SHOWN);
52162
+ return `"${cut.slice(0, Math.max(cut.lastIndexOf(" "), QUOTE_SHOWN / 2)).trimEnd()}..."`;
52163
+ }
52164
+ return detail.length <= SHORT_DETAIL ? detail : null;
52165
+ }
52166
+ /**
52167
+ * A detail as an expanded pointer shows it. Display only, so it is made safe for the round trip rather than kept
52168
+ * exact: an agent sends a body it read straight back, and `bareForm` must find where each expansion ends. A `]` or
52169
+ * a line break would end it early, and a backtick would open a code span that hides what follows; brackets become
52170
+ * parentheses, backticks quotes, and line breaks spaces. The stored detail is untouched.
52171
+ */
52172
+ var shown = (detail) => detail.replace(/\s*[\r\n]+\s*/g, " ").replace(/\[/g, "(").replace(/\]/g, ")").replace(/`/g, "'");
52173
+ /**
52174
+ * The text a reader is given: every pointer expanded in place with its sources, so an agent sees where a claim
52175
+ * came from beside the claim, at the moment it reads it, without another call. Never stored - writing reduces it
52176
+ * back with `bareForm` - and in the reply only.
52177
+ *
52178
+ * `[ref r7k2: search 2026-08-10, test 2026-08-13 yarn cloud:check, text changed since]` - each source's kind and
52179
+ * date, as much of its detail as `detailShown` gives its kind (all of it, with `full`), `text changed since` when a source vouched for words the
52180
+ * claim no longer says, and `code changed since` when a `code` source's lines are in `codeChanged`. A pointer with
52181
+ * nothing behind it says so, rather than passing as backed.
52182
+ */
52183
+ function expandPointers(text, sources, full = false, codeChanged = /* @__PURE__ */ new Set()) {
52184
+ const byKey = /* @__PURE__ */ new Map();
52185
+ for (const s of sources) byKey.set(s.key, [...byKey.get(s.key) ?? [], s]);
52186
+ const { pointers } = parsePointers(text);
52187
+ let out = "";
52188
+ let last = 0;
52189
+ for (const p of [...pointers].sort((a, b) => a.at - b.at)) {
52190
+ const behind = byKey.get(p.key) ?? [];
52191
+ const parts = behind.map((s) => {
52192
+ const detail = full ? s.source === "user" ? `"${shown(s.detail)}"` : shown(s.detail) : detailShown(s.source, shown(s.detail));
52193
+ return detail === null ? `${s.source} ${s.recordedAt.slice(0, 10)}` : `${s.source} ${s.recordedAt.slice(0, 10)} ${detail}`;
52194
+ });
52195
+ if (behind.length === 0) parts.push("no reference behind it");
52196
+ else if (normaliseClaim(behind[behind.length - 1].quotedText) !== p.covers) parts.push("text changed since");
52197
+ if (behind.some((s) => s.source === "code" && codeChanged.has(s.detail))) parts.push("code changed since");
52198
+ out += text.slice(last, p.at) + `[ref ${p.key}: ${parts.join(", ")}]`;
52199
+ last = p.at + p.written.length;
52200
+ }
52201
+ return out + text.slice(last);
52202
+ }
52203
+ /**
52204
+ * The sourced claims an edit touched, old text against new, so the writer sees them in the same reply rather than
52205
+ * finding out on the next read. Nothing is refused: a changed claim keeps its sources and will read "text changed
52206
+ * since"; a removed pointer has already been retired.
52207
+ */
52208
+ function referenceChanges(before, after, sources) {
52209
+ const was = new Map(parsePointers(before).pointers.map((p) => [p.key, p.covers]));
52210
+ const now = new Map(parsePointers(after).pointers.map((p) => [p.key, p.covers]));
52211
+ return [...new Set(sources.map((s) => s.key))].sort().flatMap((key) => {
52212
+ const summary = sources.filter((s) => s.key === key).map((s) => `${s.source} ${s.recordedAt.slice(0, 10)}`).join(", ");
52213
+ if (!now.has(key)) return was.has(key) ? [{
52214
+ key,
52215
+ kind: "retired",
52216
+ sources: summary
52217
+ }] : [];
52218
+ const before = was.get(key);
52219
+ const after = now.get(key);
52220
+ return before !== void 0 && before !== after ? [{
52221
+ key,
52222
+ kind: "changed",
52223
+ sources: summary,
52224
+ before,
52225
+ after
52226
+ }] : [];
52227
+ });
52228
+ }
51507
52229
  // src/domain/context.ts
51508
52230
  /**
51509
52231
  * Context sections (CTX): the project's living narrative as named prose blocks - "Goals", "Assumptions",
@@ -51548,6 +52270,7 @@ async function orderAfter(tx, projectId, after, movingHeading) {
51548
52270
  return index * 16 + 8;
51549
52271
  }
51550
52272
  async function setSection(db, input, actor) {
52273
+ const content = bareForm(input.content);
51551
52274
  return mutate(db, actor, async (tx) => {
51552
52275
  const existing = maybeOne(await tx.select().from(contextSections).where(and(eq(contextSections.projectId, input.projectId), eq(contextSections.heading, input.heading))));
51553
52276
  const now = timestamp();
@@ -51555,27 +52278,38 @@ async function setSection(db, input, actor) {
51555
52278
  const after = one(await tx.insert(contextSections).values({
51556
52279
  projectId: input.projectId,
51557
52280
  heading: input.heading,
51558
- content: input.content,
52281
+ content,
51559
52282
  sortOrder: order,
51560
52283
  createdAt: now,
51561
52284
  updatedAt: now
51562
52285
  }).onConflictDoUpdate({
51563
52286
  target: [contextSections.projectId, contextSections.heading],
51564
52287
  set: {
51565
- content: input.content,
52288
+ content,
51566
52289
  sortOrder: order,
51567
52290
  updatedAt: now
51568
52291
  }
51569
52292
  }).returning());
52293
+ const sourcesBefore = existing ? await liveSources(tx, { sectionId: after.id }) : [];
52294
+ const retiredReferences = existing ? await retireRemovedPointers(tx, { sectionId: after.id }, content) : [];
52295
+ const addedSources = input.sources === void 0 ? [] : await addSources(tx, input.projectId, { sectionId: after.id }, content, input.sources, actor);
51570
52296
  return {
51571
- result: after,
52297
+ result: {
52298
+ ...after,
52299
+ referenceChanges: existing ? referenceChanges(existing.content, content, sourcesBefore) : [],
52300
+ addedSources
52301
+ },
51572
52302
  event: {
51573
52303
  projectId: input.projectId,
51574
52304
  entityType: "context_section",
51575
52305
  entityId: after.id,
51576
52306
  kind: existing ? "updated" : "created",
51577
52307
  before: existing ?? void 0,
51578
- after
52308
+ after: {
52309
+ ...after,
52310
+ ...retiredReferences.length > 0 ? { retiredReferences } : {},
52311
+ ...addedSources.length > 0 ? { addedSources } : {}
52312
+ }
51579
52313
  }
51580
52314
  };
51581
52315
  });
@@ -51593,6 +52327,7 @@ async function deleteSection(db, projectId, heading, actor) {
51593
52327
  return mutate(db, actor, async (tx) => {
51594
52328
  const existing = maybeOne(await tx.select().from(contextSections).where(and(eq(contextSections.projectId, projectId), eq(contextSections.heading, heading))));
51595
52329
  if (existing === null) throw new Error(`no context section "${heading}"`);
52330
+ const references = await tx.select().from(sourceReferences).where(eq(sourceReferences.sectionId, existing.id));
51596
52331
  await tx.delete(contextSections).where(eq(contextSections.id, existing.id));
51597
52332
  return {
51598
52333
  result: existing,
@@ -51601,7 +52336,10 @@ async function deleteSection(db, projectId, heading, actor) {
51601
52336
  entityType: "context_section",
51602
52337
  entityId: existing.id,
51603
52338
  kind: "deleted",
51604
- before: existing
52339
+ before: references.length > 0 ? {
52340
+ ...existing,
52341
+ references
52342
+ } : existing
51605
52343
  }
51606
52344
  };
51607
52345
  });
@@ -51776,6 +52514,122 @@ async function metricsForFeed(db, ownerId) {
51776
52514
  }
51777
52515
  return out;
51778
52516
  }
52517
+ // src/mcp/codeDrift.ts
52518
+ /**
52519
+ * Whether the code a `code` source pinned has changed since (`CTX-13`): the lines at the pinned commit against the
52520
+ * same lines of the file as it is now.
52521
+ *
52522
+ * **Only where it is cheap and possible, and only when one item or section is read** - `get_item`, `get_context`
52523
+ * and the pane opening an item; never a listing, a search or `get_project`, and at most `MAX_CODE_CHECKS` a read. The pinned lines are fetched for every
52524
+ * source in one `git cat-file --batch` process (measured 2026-11-15: about 0.25 ms a file batched, 2 ms spawning git
52525
+ * per file), so a read with a few code references pays a few milliseconds. A host with no checkout - the hosted
52526
+ * server - never calls this, and in a checkout without the pinned commit (a shallow clone: CI, a cloud session) the
52527
+ * source is simply not reported: unknown is not changed. The reference still says exactly what a claim rests on, so
52528
+ * an agent relying on it can run the `git show` itself.
52529
+ *
52530
+ * **Moved is not changed.** The pinned lines are looked for anywhere in the file now, not only at their old line
52531
+ * numbers, so an import added above them does not flag every reference below it. Only text that is no longer in the
52532
+ * file at all reads as changed, which is the signal worth having; a reference whose line numbers drifted still
52533
+ * names a commit where they were right.
52534
+ *
52535
+ * Node-only, so it lives with the server rather than beside the shared parser.
52536
+ */
52537
+ /** Run git and take its output as bytes: `cat-file` sizes its objects in bytes, so a text decode would misalign. */
52538
+ var run = (args, cwd, input) => new Promise((resolve, reject) => {
52539
+ const child = execFile("git", args, {
52540
+ cwd,
52541
+ encoding: "buffer",
52542
+ maxBuffer: 67108864,
52543
+ timeout: 2e3
52544
+ }, (error, stdout) => error ? reject(error) : resolve(stdout));
52545
+ if (input !== void 0) child.stdin?.end(input);
52546
+ });
52547
+ /**
52548
+ * How many `code` sources one read checks. A read is one item or one section, so this is a body that leans on a lot
52549
+ * of code; past it the rest are not checked and so not reported, which is what an unchecked source always means
52550
+ * here - unknown, never changed. Keeps a heavily referenced body from costing a large batch and a scan of each file
52551
+ * on every read.
52552
+ */
52553
+ var MAX_CODE_CHECKS = 20;
52554
+ /** Each plan file's checkout, looked up once a process: a plan file does not move between repos while it runs. */
52555
+ var checkouts = /* @__PURE__ */ new Map();
52556
+ /** The checkout a plan file sits in, or null when it is not in one (or git is not there to ask). */
52557
+ function checkoutOf(planPath) {
52558
+ let found = checkouts.get(planPath);
52559
+ if (found === void 0) {
52560
+ found = run(["rev-parse", "--show-toplevel"], dirname(planPath)).then((out) => out.toString("utf8").trim() || null, () => null);
52561
+ checkouts.set(planPath, found);
52562
+ }
52563
+ return found;
52564
+ }
52565
+ /**
52566
+ * `git cat-file --batch` output for `commit:path` objects, by request: the file's text, or null for each one git
52567
+ * does not have or that is not a file. Every object's bytes are stepped over whatever its type, since a `tree` or a
52568
+ * `commit` is followed by its content just as a blob is, and losing count there would file every later blob under
52569
+ * the wrong request.
52570
+ */
52571
+ async function blobsAt(root, refs) {
52572
+ const requests = refs.map((ref) => `${ref.commit}:${ref.path}`);
52573
+ const out = await run(["cat-file", "--batch"], root, requests.join("\n") + "\n");
52574
+ const blobs = [];
52575
+ let at = 0;
52576
+ for (let i = 0; i < requests.length; i++) {
52577
+ const end = out.indexOf(10, at);
52578
+ if (end === -1) break;
52579
+ const header = out.subarray(at, end).toString();
52580
+ at = end + 1;
52581
+ const object = /^\S+ (\S+) (\d+)$/.exec(header);
52582
+ if (object === null) {
52583
+ blobs.push(null);
52584
+ continue;
52585
+ }
52586
+ const size = Number(object[2]);
52587
+ blobs.push(object[1] === "blob" ? out.subarray(at, at + size).toString("utf8") : null);
52588
+ at += size + 1;
52589
+ }
52590
+ return blobs;
52591
+ }
52592
+ /** A file's lines with trailing whitespace dropped, so a reformatted line end never reads as a change. A final
52593
+ * newline ends the last line rather than starting an empty one. */
52594
+ var linesOf = (text) => text.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n").map((line) => line.trimEnd());
52595
+ /** Lines `from` to `to` (1-based, inclusive) of the file, or null when the file is shorter. */
52596
+ function pinned(all, from, to) {
52597
+ return to > all.length ? null : all.slice(from - 1, to);
52598
+ }
52599
+ /** Whether `lines` appear, consecutively and in order, anywhere in `file`. */
52600
+ function contains(file, lines) {
52601
+ for (let start = 0; start + lines.length <= file.length; start++) if (lines.every((line, offset) => file[start + offset] === line)) return true;
52602
+ return false;
52603
+ }
52604
+ /**
52605
+ * The details of the `code` sources whose pinned lines are no longer in the file, in the checkout holding
52606
+ * `planFile` - the plan file that owns what is being read, so a plan spread over several repos checks each against
52607
+ * its own. Empty when there is no plan file (the hosted server passes none), no checkout or no code source; never
52608
+ * throws, since a read must not fail over an optional check.
52609
+ */
52610
+ async function codeDrift(planFile, sources) {
52611
+ const changed = /* @__PURE__ */ new Set();
52612
+ const code = [...new Set(sources.filter((s) => s.source === "code").map((s) => s.detail))].flatMap((detail) => {
52613
+ const ref = parseCodeRef(detail);
52614
+ return ref === null ? [] : [{
52615
+ detail,
52616
+ ref
52617
+ }];
52618
+ }).slice(0, 20);
52619
+ if (code.length === 0 || planFile === void 0) return changed;
52620
+ try {
52621
+ const root = await checkoutOf(planFile);
52622
+ if (root === null) return changed;
52623
+ const then = await blobsAt(root, code.map((c) => c.ref));
52624
+ await Promise.all(code.map(async ({ detail, ref }, index) => {
52625
+ const was = then[index] === null || then[index] === void 0 ? null : pinned(linesOf(then[index]), ref.from, ref.to);
52626
+ if (was === null) return;
52627
+ const now = await readFile(join(root, ref.path), "utf8").then(linesOf, () => null);
52628
+ if (now === null || !contains(now, was)) changed.add(detail);
52629
+ }));
52630
+ } catch {}
52631
+ return changed;
52632
+ }
51779
52633
  // src/domain/dependencies.ts
51780
52634
  /**
51781
52635
  * The dependency graph (MCP-16, MCP-17): the edges between items, and the two integrity rules that make
@@ -52240,20 +53094,27 @@ async function createItem(db, input, actor) {
52240
53094
  sortPath: path,
52241
53095
  parentId,
52242
53096
  title: input.title,
52243
- body: input.body ?? null,
53097
+ body: input.body === void 0 ? null : bareForm(input.body),
52244
53098
  status,
52245
53099
  startOn,
52246
53100
  dueOn
52247
53101
  }).returning());
52248
53102
  if (input.deps && input.deps.length > 0) await setDependencies(tx, item, input.deps);
53103
+ const addedSources = input.sources === void 0 ? [] : await addSources(tx, input.projectId, { itemId: item.id }, item.body ?? "", input.sources, actor);
52249
53104
  return {
52250
- result: item,
53105
+ result: {
53106
+ ...item,
53107
+ addedSources
53108
+ },
52251
53109
  event: {
52252
53110
  projectId: input.projectId,
52253
53111
  entityType: "item",
52254
53112
  entityId: item.id,
52255
53113
  kind: "created",
52256
- after: item
53114
+ after: addedSources.length > 0 ? {
53115
+ ...item,
53116
+ addedSources
53117
+ } : item
52257
53118
  }
52258
53119
  };
52259
53120
  });
@@ -52348,21 +53209,29 @@ async function setStatus(db, args, actor) {
52348
53209
  * touches it; at least one field must be given. The whole before/after is logged, so the edit is auditable
52349
53210
  * and reversible like any other mutation. */
52350
53211
  async function editItem(db, input, actor) {
52351
- if (input.title === void 0 && input.body === void 0 && input.deps === void 0 && input.start === void 0 && input.due === void 0) throw new Error("nothing to edit: provide a title, body, deps, start and/or due");
53212
+ if (input.title === void 0 && input.body === void 0 && input.deps === void 0 && input.start === void 0 && input.due === void 0 && input.sources === void 0) throw new Error("nothing to edit: provide a title, body, deps, start, due and/or sources");
52352
53213
  return mutate(db, actor, async (tx) => {
52353
53214
  const before = maybeOne(await tx.select().from(items).where(and(eq(items.projectId, input.projectId), eq(items.ref, input.ref))));
52354
53215
  if (before === null) throw new Error(`no ticket "${input.ref}" in this project`);
52355
53216
  const changes = { updatedAt: timestamp() };
52356
53217
  if (input.title !== void 0) changes.title = input.title;
52357
- if (input.body !== void 0) changes.body = input.body;
53218
+ if (input.body !== void 0) changes.body = bareForm(input.body);
52358
53219
  if (input.start !== void 0) changes.startOn = input.start;
52359
53220
  if (input.due !== void 0) changes.dueOn = input.due;
52360
53221
  assertDates(input.start === void 0 ? before.startOn : input.start, input.due === void 0 ? before.dueOn : input.due);
52361
53222
  const after = one(await tx.update(items).set(changes).where(eq(items.id, before.id)).returning());
53223
+ const sourcesBefore = input.body === void 0 ? [] : await liveSources(tx, { itemId: before.id });
53224
+ const retiredReferences = input.body === void 0 ? [] : await retireRemovedPointers(tx, { itemId: before.id }, after.body ?? "");
53225
+ const addedSources = input.sources === void 0 ? [] : await addSources(tx, input.projectId, { itemId: before.id }, after.body ?? "", input.sources, actor);
53226
+ const changedReferences = input.body === void 0 ? [] : referenceChanges(before.body ?? "", after.body ?? "", sourcesBefore);
52362
53227
  const beforeDeps = input.deps === void 0 ? void 0 : await dependencyRefs(tx, before.id);
52363
53228
  const afterDeps = input.deps === void 0 ? void 0 : await setDependencies(tx, before, input.deps);
52364
53229
  return {
52365
- result: after,
53230
+ result: {
53231
+ ...after,
53232
+ referenceChanges: changedReferences,
53233
+ addedSources
53234
+ },
52366
53235
  event: {
52367
53236
  projectId: input.projectId,
52368
53237
  entityType: "item",
@@ -52374,7 +53243,9 @@ async function editItem(db, input, actor) {
52374
53243
  },
52375
53244
  after: {
52376
53245
  ...after,
52377
- deps: afterDeps
53246
+ deps: afterDeps,
53247
+ ...retiredReferences.length > 0 ? { retiredReferences } : {},
53248
+ ...addedSources.length > 0 ? { addedSources } : {}
52378
53249
  }
52379
53250
  }
52380
53251
  };
@@ -52906,16 +53777,20 @@ async function removeAttachment(db, projectId, hash, actor) {
52906
53777
  /** Comments on one item, all of them: the pane shows the whole record, and a busy item has a few dozen. */
52907
53778
  var COMMENT_LIMIT = 500;
52908
53779
  /** Null when the owner has no such project, or the project no such live item; a host answers 404. */
52909
- async function itemFeed(db, ownerId, projectKey, ref) {
53780
+ async function itemFeed(db, ownerId, projectKey, ref, drift) {
52910
53781
  const project = await getProjectByKey(db, ownerId, projectKey);
52911
53782
  if (project === null) return null;
52912
53783
  const item = await getItem(db, project.id, ref);
52913
53784
  if (item === null || item.deletedAt !== null) return null;
52914
- const [comments, attachments] = await Promise.all([listComments(db, {
52915
- projectId: project.id,
52916
- itemId: item.id,
52917
- limit: COMMENT_LIMIT
52918
- }), listAttachments(db, project.id, ref)]);
53785
+ const [comments, attachments, references] = await Promise.all([
53786
+ listComments(db, {
53787
+ projectId: project.id,
53788
+ itemId: item.id,
53789
+ limit: COMMENT_LIMIT
53790
+ }),
53791
+ listAttachments(db, project.id, ref),
53792
+ liveSources(db, { itemId: item.id })
53793
+ ]);
52919
53794
  return {
52920
53795
  ref: item.ref,
52921
53796
  body: item.body ?? "",
@@ -52932,7 +53807,18 @@ async function itemFeed(db, ownerId, projectKey, ref) {
52932
53807
  bytes: a.bytes,
52933
53808
  ...a.caption ? { caption: a.caption } : {},
52934
53809
  at: a.createdAt
52935
- }))
53810
+ })),
53811
+ references: await (async () => {
53812
+ const changed = drift === void 0 ? /* @__PURE__ */ new Set() : await drift(references);
53813
+ return references.map((r) => ({
53814
+ key: r.key,
53815
+ source: r.source,
53816
+ detail: r.detail,
53817
+ text: r.quotedText,
53818
+ at: r.recordedAt,
53819
+ ...r.source === "code" && changed.has(r.detail) ? { codeChanged: true } : {}
53820
+ }));
53821
+ })()
52936
53822
  };
52937
53823
  }
52938
53824
  // src/domain/layout.ts
@@ -53232,7 +54118,11 @@ function createViewerHost(db, sources, store, caller) {
53232
54118
  if (!sameOrigin(request, bound)) return json(403, { error: "cross-origin writes are refused" });
53233
54119
  return null;
53234
54120
  };
53235
- const changes = createChangeFeed((store.paths?.() ?? []).flatMap((path) => [path, layoutPathFor(path)]), async () => {
54121
+ const changes = createChangeFeed((store.paths?.() ?? []).flatMap((path) => [
54122
+ path,
54123
+ layoutPathFor(path),
54124
+ referencesPathFor(path)
54125
+ ]), async () => {
53236
54126
  await store.refresh();
53237
54127
  return (await versionFeed(db, caller.ownerId, store.reloads?.() ?? 0)).version;
53238
54128
  });
@@ -53265,7 +54155,7 @@ function createViewerHost(db, sources, store, caller) {
53265
54155
  }));
53266
54156
  }
53267
54157
  if (path === "/api/item") {
53268
- const found = await itemFeed(db, caller.ownerId, params.get("project") ?? "", params.get("ref") ?? "");
54158
+ const found = await itemFeed(db, caller.ownerId, params.get("project") ?? "", params.get("ref") ?? "", (sources) => codeDrift(store.planFileOf?.(params.get("project") ?? ""), sources));
53269
54159
  return found === null ? json(404, { error: `no item "${params.get("ref") ?? ""}" in "${params.get("project") ?? ""}"` }) : json(200, found);
53270
54160
  }
53271
54161
  if (path === "/api/search") {
@@ -53580,6 +54470,23 @@ function redact(url) {
53580
54470
  return "<unparseable connection string>";
53581
54471
  }
53582
54472
  }
54473
+ // src/mcp/referenceReplies.ts
54474
+ /**
54475
+ * How a writing tool reports what it did to source references (`CTX-13`). Reply formatting, so it lives with the
54476
+ * tools rather than in `domain/`, which returns the facts: the sources added, the sourced claims an edit changed or
54477
+ * retired, and anything about the pointers a writer should hear now rather than from `apm:check` later.
54478
+ */
54479
+ /** The sourced claims an edit touched, as lines. Empty when nothing sourced was touched, so a reply stays as it was. */
54480
+ function fmtReferenceChanges(changes) {
54481
+ if (changes.length === 0) return "";
54482
+ return `\nsourced claims you changed:\n${changes.map((c) => c.kind === "retired" ? `- ${c.key} (${c.sources}): pointer removed, so its sources were retired` : `- ${c.key} (${c.sources}): "${c.before}" -> "${c.after}". Kept; reads "text changed since" until a source is added for the new text`).join("\n")}`;
54483
+ }
54484
+ /** The keys sources were added to, from what was actually inserted, and the problems with the text's pointers. */
54485
+ function fmtSourcesWritten(added, text) {
54486
+ const keys = [...new Set(added.map((a) => a.key))];
54487
+ const problems = text === null ? [] : parsePointers(text).problems.map((p) => p.problem);
54488
+ return (keys.length > 0 ? `\nsources added to: ${keys.join(", ")}` : "") + (problems.length > 0 ? `\npointer problems (the text is saved; fix these with another edit):\n${problems.map((p) => `- ${p}`).join("\n")}` : "");
54489
+ }
53583
54490
  // src/domain/areas.ts
53584
54491
  /**
53585
54492
  * Areas: the ref prefix that groups items, and the metadata a project can attach to one.
@@ -53917,6 +54824,18 @@ var date = (what, more) => string().describe(dateText(what, more));
53917
54824
  * a description set first lands on the string branch inside it, where a client showing the field never looks.
53918
54825
  */
53919
54826
  var clearableDate = (what) => string().nullable().describe(dateText(`${what}; null clears it`));
54827
+ /**
54828
+ * Where claims in some prose came from (`CTX-13`), shared by every tool that writes prose. Kept to one parameter's
54829
+ * description rather than a tool of its own, because every tool description sits in every conversation's context:
54830
+ * this is the whole of the guidance, and it says once what the rest of the design does.
54831
+ */
54832
+ var SOURCE = object({
54833
+ source: _enum(SOURCE_KINDS),
54834
+ detail: string().min(1).max(500).describe("For user, their words verbatim; for test, the command; for search, the URL; for docs, the file or page; for code, path:line or path:from-to@commit (e.g. src/db/schema.ts:120-140@345a746).")
54835
+ });
54836
+ /** Bounds on one write, so a reply that inlines every source stays readable and one call cannot insert thousands. */
54837
+ var MAX_KEYS = 20;
54838
+ var SOURCES = record(string().regex(/^[a-z0-9]{1,16}$/, "a key is 1 to 16 lowercase letters and digits"), union$1([SOURCE, array(SOURCE).min(1).max(5)])).refine((sources) => Object.keys(sources).length > 0, "name at least one key, or leave sources out").refine((sources) => Object.keys(sources).length <= MAX_KEYS, `at most ${MAX_KEYS} keys in one write`).describe("Where claims in this text came from, when it is more than your own reasoning. Write a pointer straight after the claim, like \"Postgres 18.4 runs in production [ref pg18].\", and give its sources here keyed by it: {\"pg18\": {\"source\": \"test\", \"detail\": \"yarn cloud:check\"}}. Keys are short lowercase letters and digits, unused elsewhere in the project. A key already sourced here gains another source. Unreferenced text is yours by default, so reference only claims with a real source.").optional();
53920
54839
  var DEPS = array(string()).describe("Refs this item depends on (must be done first). Replaces the whole set; pass [] to clear it. A ref may name another project, as `key:REF` (e.g. `apm:DIST-1`), which is how an edge survives a plan split across store files; it stays valid when that project is not loaded.").optional();
53921
54840
  /**
53922
54841
  * A list read as prose: "kg", "kg and lb", "kg, lb and stone".
@@ -54381,7 +55300,7 @@ function registerTools(server, db, store, viewer, caller) {
54381
55300
  }));
54382
55301
  server.registerTool("set_next", {
54383
55302
  annotations: WRITE,
54384
- description: "Record the order to work in: a short list of item refs, most important first. Replaces the whole list (pass [] to clear it), because a list you can only append to is one nobody re-examines. Keep it to five or ten - the shortness is what forces \"does this beat what is already third?\", which is what produces an ordering at all. This is a stated intention, not a constraint: it does not gate anything, and an item whose dependencies are unmet is flagged rather than refused. get_project reads it back, so this is how an agreed order survives the conversation that produced it.",
55303
+ description: "Record the order to work in: item refs, most important first. Replaces the whole list (pass [] to clear it), because a list you can only append to is one nobody re-examines. Rank it rather than collect into it: each ref's place should say what it beats. This is a stated intention, not a constraint: it does not gate anything, and an item whose dependencies are unmet is flagged rather than refused. get_project reads it back, so this is how an agreed order survives the conversation that produced it.",
54385
55304
  inputSchema: {
54386
55305
  project: string(),
54387
55306
  refs: array(string()).describe("Item refs in the order to work on them. Replaces the whole list; pass [] to clear it.")
@@ -54405,9 +55324,10 @@ function registerTools(server, db, store, viewer, caller) {
54405
55324
  status: _enum(STATUS_VALUES).describe("Defaults to to-do.").optional(),
54406
55325
  deps: DEPS,
54407
55326
  start: date("When work on it is planned to begin", "Optional; most items have no dates.").optional(),
54408
- due: date("When it is due", "Optional; most items have no dates.").optional()
55327
+ due: date("When it is due", "Optional; most items have no dates.").optional(),
55328
+ sources: SOURCES
54409
55329
  }
54410
- }, async ({ project, area, parent, ref, title, body, status, deps, start, due }) => guarded(async () => {
55330
+ }, async ({ project, area, parent, ref, title, body, status, deps, start, due, sources }) => guarded(async () => {
54411
55331
  const item = await createItem(db, {
54412
55332
  projectId: (await resolveProject(db, caller, project)).id,
54413
55333
  area,
@@ -54418,10 +55338,11 @@ function registerTools(server, db, store, viewer, caller) {
54418
55338
  status,
54419
55339
  deps,
54420
55340
  start,
54421
- due
55341
+ due,
55342
+ sources
54422
55343
  }, ACTOR);
54423
55344
  await store.persist();
54424
- return text(`created ${fmtItem(item)}${deps?.length ? `\ndepends on: ${deps.join(", ")}` : ""}`);
55345
+ return text(`created ${fmtItem(item)}${deps?.length ? `\ndepends on: ${deps.join(", ")}` : ""}${fmtSourcesWritten(item.addedSources, item.body)}`);
54425
55346
  }));
54426
55347
  server.registerTool("list_items", {
54427
55348
  annotations: READ,
@@ -54496,16 +55417,24 @@ function registerTools(server, db, store, viewer, caller) {
54496
55417
  }));
54497
55418
  server.registerTool("get_item", {
54498
55419
  annotations: READ,
54499
- description: "Read one item in full by its ref: status, title, dependencies, its body (the prose the viewer's detail pane shows), and any comments recorded against it. Use list_items to find the ref.",
55420
+ description: "Read one item in full by its ref: status, title, dependencies, its body (the prose the viewer's detail pane shows), and any comments recorded against it. Use list_items to find the ref. A claim followed by [ref key: ...] has sources, named with their dates; \"text changed since\" means the claim was edited after its source vouched for it.",
54500
55421
  inputSchema: {
54501
55422
  project: string(),
54502
- ref: string()
55423
+ ref: string(),
55424
+ references: _enum(["full"]).describe("\"full\" includes every source's detail in full; otherwise a code location always shows, a quote up to about 100 characters, and other details only when short.").optional()
54503
55425
  }
54504
- }, async ({ project, ref }) => guarded(async () => {
55426
+ }, async ({ project, ref, references }) => guarded(async () => {
54505
55427
  const p = await resolveProject(db, caller, project);
54506
- const detail = await getItemDetail(db, p.id, ref);
54507
- if (detail === null) throw await noSuchRef(db, p, ref);
54508
- return text(fmtItemDetail(detail));
55428
+ const found = await getItemDetail(db, p.id, ref);
55429
+ if (found === null) throw await noSuchRef(db, p, ref);
55430
+ const sources = found.item.body === null ? [] : await liveSources(db, { itemId: found.item.id });
55431
+ return text(fmtItemDetail(found.item.body === null ? found : {
55432
+ ...found,
55433
+ item: {
55434
+ ...found.item,
55435
+ body: expandPointers(found.item.body, sources, references === "full", await codeDrift(store.planFileOf?.(p.key), sources))
55436
+ }
55437
+ }));
54509
55438
  }));
54510
55439
  server.registerTool("set_status", {
54511
55440
  annotations: WRITE,
@@ -54536,9 +55465,10 @@ function registerTools(server, db, store, viewer, caller) {
54536
55465
  body: string().describe("The item's description, in markdown.").optional(),
54537
55466
  deps: DEPS,
54538
55467
  start: clearableDate("When work on it is planned to begin").optional(),
54539
- due: clearableDate("When it is due").optional()
55468
+ due: clearableDate("When it is due").optional(),
55469
+ sources: SOURCES
54540
55470
  }
54541
- }, async ({ project, ref, title, body, deps, start, due }) => guarded(async () => {
55471
+ }, async ({ project, ref, title, body, deps, start, due, sources }) => guarded(async () => {
54542
55472
  const p = await resolveProject(db, caller, project);
54543
55473
  await resolveRef(db, p, ref);
54544
55474
  for (const dep of deps ?? []) if (splitScope(dep) === null) await resolveRef(db, p, dep);
@@ -54549,10 +55479,11 @@ function registerTools(server, db, store, viewer, caller) {
54549
55479
  body,
54550
55480
  deps,
54551
55481
  start,
54552
- due
55482
+ due,
55483
+ sources
54553
55484
  }, ACTOR);
54554
55485
  await store.persist();
54555
- return text(`edited ${fmtItem(item)}${deps ? `\ndepends on: ${deps.length ? deps.join(", ") : "(nothing)"}` : ""}`);
55486
+ return text(`edited ${fmtItem(item)}${deps ? `\ndepends on: ${deps.length ? deps.join(", ") : "(nothing)"}` : ""}${fmtSourcesWritten(item.addedSources, body === void 0 ? null : item.body)}${fmtReferenceChanges(item.referenceChanges)}`);
54556
55487
  }));
54557
55488
  server.registerTool("delete_item", {
54558
55489
  annotations: WRITE,
@@ -54661,16 +55592,18 @@ function registerTools(server, db, store, viewer, caller) {
54661
55592
  }));
54662
55593
  server.registerTool("get_context", {
54663
55594
  annotations: READ,
54664
- description: "Read one context section by its exact heading, so it can be revised from its current content. Use list_context to see the headings; get_project already returns `protocol` in full.",
55595
+ description: "Read one context section by its exact heading, so it can be revised from its current content. Use list_context to see the headings; get_project already returns `protocol` in full. A claim followed by [ref key: ...] has sources, named with their dates; \"text changed since\" means the claim was edited after its source vouched for it.",
54665
55596
  inputSchema: {
54666
55597
  project: string(),
54667
- heading: string()
55598
+ heading: string(),
55599
+ references: _enum(["full"]).describe("\"full\" includes every source's detail in full; otherwise a code location always shows, a quote up to about 100 characters, and other details only when short.").optional()
54668
55600
  }
54669
- }, async ({ project, heading }) => guarded(async () => {
55601
+ }, async ({ project, heading, references }) => guarded(async () => {
54670
55602
  const p = await resolveProject(db, caller, project);
54671
55603
  const section = await getSection(db, p.id, heading);
54672
55604
  if (section === null) throw await noSuchSection(db, p, heading);
54673
- return text(`### ${section.heading}\n${section.content}`);
55605
+ const sources = await liveSources(db, { sectionId: section.id });
55606
+ return text(`### ${section.heading}\n${expandPointers(section.content, sources, references === "full", await codeDrift(store.planFileOf?.(p.key), sources))}`);
54674
55607
  }));
54675
55608
  server.registerTool("set_context", {
54676
55609
  annotations: WRITE,
@@ -54679,20 +55612,22 @@ function registerTools(server, db, store, viewer, caller) {
54679
55612
  project: string(),
54680
55613
  heading: string(),
54681
55614
  content: string().describe("Markdown."),
54682
- after: string().describe("Place this section immediately after the named one. Pass \"\" to put it first. Omit to append, or to leave an existing section where it is.").optional()
55615
+ after: string().describe("Place this section immediately after the named one. Pass \"\" to put it first. Omit to append, or to leave an existing section where it is.").optional(),
55616
+ sources: SOURCES
54683
55617
  }
54684
- }, async ({ project, heading, content, after }) => guarded(async () => {
55618
+ }, async ({ project, heading, content, after, sources }) => guarded(async () => {
54685
55619
  const p = await resolveProject(db, caller, project);
54686
55620
  const placement = after === void 0 ? void 0 : after === "" ? null : after;
54687
55621
  const section = await setSection(db, {
54688
55622
  projectId: p.id,
54689
55623
  heading,
54690
55624
  content,
54691
- after: placement
55625
+ after: placement,
55626
+ sources
54692
55627
  }, ACTOR);
54693
55628
  await store.persist();
54694
55629
  const order = (await listSections(db, p.id)).map((s) => s.heading);
54695
- return text(`set context section "${section.heading}"\norder: ${order.join(" -> ")}`);
55630
+ return text(`set context section "${section.heading}"\norder: ${order.join(" -> ")}${fmtSourcesWritten(section.addedSources, section.content)}${fmtReferenceChanges(section.referenceChanges)}`);
54696
55631
  }));
54697
55632
  server.registerTool("delete_context", {
54698
55633
  annotations: WRITE,