@anchrd/intel 0.59.0

package/dist/contract/contract.js

@@ -0,0 +1,143 @@
+import { z } from "zod";
+export const IntelId = z.string().min(1).max(128);
+export const IsoDateTime = z.iso.datetime({ offset: true });
+// ⚠️ One described primitive rather than the same sentence on twenty-odd fields (#398). The word
+// `idempotencyKey` means exactly the same thing everywhere it appears, and a reader who learns it
+// once at `node_create` should not have to re-read it at `flow_publish`. Twenty copies of one
+// sentence is also twenty places for it to drift, and `tools/list` would carry every copy.
+//
+// The description says what the caller has to DO, because that is the part a model gets wrong: it
+// invents a fresh key on the retry and creates the thing twice.
+export const IdempotencyKey = z
+    .string()
+    .min(8)
+    .max(200)
+    .describe("A caller-chosen key that makes this call safe to retry: repeating the same key returns the first result instead of doing the work twice. Reuse the SAME key when retrying one attempt, and a new one for a genuinely new call.");
+/**
+ * The short name a document or a published flow is offered under as a slash command (#775).
+ *
+ * ⚠️ One described primitive rather than the same sentence in two files, for the reason
+ * `IdempotencyKey` above gives: a document and a flow take the same kind of name out of the same
+ * catalogue, and a copy would be a second place for one sentence to drift. It sits here rather than
+ * in `node.ts` because `flow.ts` states it too, and this is the file both may read.
+ *
+ * ⚠️ The refusal spells the GRAMMAR, not the verdict. Zod's own `Invalid` tells a caller who sent
+ * `CRM Outreach` that something was wrong and not what would have worked, and the one thing they
+ * need is that the answer is `crm-outreach`.
+ *
+ * ⚠️ Uniqueness is NOT in this schema and cannot be: it is a question about the whole installation,
+ * across documents and flows at once, and it is answered where the write happens. A name another
+ * node or flow already holds is refused by name there, never quietly turned into a second one.
+ */
+export const PromptName = z
+    .string()
+    .regex(/^[a-z0-9-]{1,40}$/, {
+    error: "A prompt name is 1 to 40 characters of lowercase letters, digits and hyphens, and nothing else: `crm-outreach`.",
+})
+    .describe("The slash command this is offered under, written without the leading slash: `crm-outreach` reaches a client as `/crm-outreach`. Lowercase letters, digits and hyphens only, and unique over every document and flow in the installation — a name one of them already holds is refused and names its holder, never silently changed into another one.");
+/**
+ * The version a write is made against, in the one form every writer of versioned content takes it.
+ *
+ * ⚠️ It lived beside the two node writers until #459 and moved here when the flow graph became the
+ * third — the point at which the repository stops copying and names the thing. It could not simply
+ * be imported: `flow.ts` may not depend on `node.ts` (the graph is `table → node`, `flow-run →
+ * flow`, and everything → here), and a copy would have been a second place for one sentence to
+ * drift, which is exactly what `IdempotencyKey` above exists to avoid.
+ *
+ * ⚠️ Nullable and required are not the same thing, and here they stand together (#437). `null` is
+ * how something that has no version yet is addressed, and it is the only way to write its first
+ * content; leaving the field out says nothing at all and is refused. Whoever leaves it out is
+ * almost always holding a node or a flow created one call earlier, and the plain type error they
+ * used to get — "expected string, received undefined" — reads as "this field must be an id", about
+ * a field that cannot have one yet. Both refusals therefore name both ways instead.
+ *
+ * ⚠️ It stays required once a version exists, and that is what it is for: a mismatch is answered
+ * with a `409` rather than by overwriting somebody else's newer version. Making it `optional()` to
+ * smooth the first write is the repair that breaks the guard — an absent field would then have to
+ * mean "there is none", and the forgetful caller silently replaces the newest one.
+ *
+ * ⚠️ The bounds remain `IntelId`'s. The repeated `min(1)` adds no rule — it only puts the sentence
+ * on the second value that gets tried after `undefined`, the empty string.
+ *
+ * ⚠️ The sentence says what the field TAKES, not what the caller did wrong. It answers a wrong type
+ * as well as an absent field, and "is required" would be false about the first — which would be
+ * this same ticket one corner further on. A value that is merely too long keeps Zod's own `Too
+ * big`: that one is already a true statement about what was sent.
+ *
+ * ⚠️ The JSON Schema it produces is the one `IntelId.nullable()` produced — an `anyOf` of the
+ * bounded string and `null`, still `required` — so nothing on the MCP surface moves when a field
+ * changes over to it.
+ */
+export function baseVersion(rule) {
+    return z.union([IntelId.min(1, { error: rule }), z.null()], { error: rule });
+}
+// The languages whose UI catalog ships inside the surface. They live here rather than only in the UI
+// because `intel build` has to know them: a built-in language may be chosen as `ui.defaultLanguage`
+// without the customer listing a copy under `ui.languages` that would rot at every UI update.
+//
+// ⚠️ The list is a claim about the contents of packages/intel/ui/src/i18n and cannot be checked here.
+// `i18n.unit.ts` compares it against the catalogs actually built in; a language listed here without
+// a file gives a red run there instead of a UI that starts on a catalog which does not exist.
+export const UI_LANGUAGES = ["en", "de", "es"];
+/**
+ * A set of things the reader is only partly entitled to see: the ones they may see BY NAME, the
+ * rest as a NUMBER (ADR-0004 §3). Never the titles of the rest, in any field, ever — a warning or a
+ * refusal must not become a way of reading the tree.
+ *
+ * ⚠️ It lives here rather than in `share.ts` because two domains state it: a grant says what it
+ * does not reach (`UnreadableNodes`), and a refusal says who is still calling in
+ * (`ProblemDetails.callers`, #448). `contract.ts` may not import from `share.ts` — the graph
+ * between these files has to stay acyclic — and a copy would be a second place for one rule to
+ * drift, which is what `IdempotencyKey` and `baseVersion` above exist against.
+ */
+export const NamedOrCounted = z.strictObject({
+    titles: z.array(z.string().min(1).max(240)),
+    hidden: z.number().int().nonnegative(),
+});
+/**
+ * ⚠️ `callers` is the one member here that is not about every problem, and it is deliberate (#448).
+ * RFC 9457 allows extension members for exactly this: `folder_execute_in_use` refuses to narrow a
+ * library folder while flows from outside still call into it, and the CALLERS are the only thing
+ * that makes the refusal actionable. They used to exist only inside `detail` — an English sentence
+ * built on the server — so a German or Spanish surface could do nothing but print it verbatim, and
+ * no surface could shorten it or link the titles.
+ *
+ * The split is the point: the server decides WHAT is named and what is only counted, because that
+ * is an authorization answer nobody else can give; the surface decides how the sentence READS,
+ * because that is a language answer no server can give.
+ *
+ * `detail` keeps its sentence rather than emptying out — MCP hands a model prose and has nothing to
+ * formulate with, and an empty `detail` beside a new field would be the worst of the three states.
+ * It is absent on every other problem, so a reader must not treat its presence as guaranteed.
+ */
+export const ProblemDetails = z.strictObject({
+    type: z.string(),
+    status: z.number().int().min(400).max(599),
+    title: z.string(),
+    detail: z.string().optional(),
+    instance: z.string().optional(),
+    code: z.string().optional(),
+    callers: NamedOrCounted.optional(),
+});
+// Who the caller is, as Gate resolved it from the bearer: no token, and no capability list.
+//
+// ⚠️ `isAdmin` is the one exception, and it is a DRAWING instruction rather than a permission
+// (#416). MCP hides what a caller may not do by never registering the tool, so a model never sees a
+// door it cannot open; the browser has no equivalent and would have to offer an admin action to
+// everybody and answer with a 403. One boolean is what the shell needs to not do that.
+//
+// Two things keep it from becoming a capability list by degrees: it says what the shell may DRAW,
+// never what the server may do — every door still asks Gate itself — and it is one field with one
+// consumer. A second one is a second reason, written down when it exists.
+export const SessionUser = z.strictObject({
+    id: IntelId,
+    email: z.email(),
+    name: z.string().min(1).max(240).nullable(),
+    isAdmin: z.boolean(),
+});
+// One reference, never a list. The old `knowledge` node carried up to a hundred, plus a retrieval
+// mode and a query that nothing read — three things in one, and the last two describing a retrieval
+// Intel does not perform (D24: the agent fetches, Intel does not put anything into a context).
+// Splitting by kind is what makes "exactly one" sayable at all, and it lets the editor filter the
+// picker by what the node is for.
+export const LinkConfiguration = z.strictObject({ resourceId: IntelId });

package/dist/contract/feed.d.ts

@@ -0,0 +1,126 @@
+import { z } from "zod";
+export declare const FeedAction: z.ZodEnum<{
+    "node.create": "node.create";
+    "node.save": "node.save";
+    "node.append": "node.append";
+    "node.update": "node.update";
+    "node.archive": "node.archive";
+    "node.share": "node.share";
+    "node.revoke": "node.revoke";
+    "flows.create": "flows.create";
+    "flows.update": "flows.update";
+    "flows.archive": "flows.archive";
+    "flows.save": "flows.save";
+    "flows.publish": "flows.publish";
+    "flows.complete": "flows.complete";
+    "flows.cancel": "flows.cancel";
+    "flows.unpublish": "flows.unpublish";
+    "flows.share": "flows.share";
+    "flows.revoke": "flows.revoke";
+    "node.purge": "node.purge";
+    "flows.purge": "flows.purge";
+}>;
+export type FeedAction = z.infer<typeof FeedAction>;
+/**
+ * What an entry is about. Derived from the action rather than carried separately: the two can then
+ * never disagree, and a reader that has to draw a flow differently from a document does not depend
+ * on a second field being filled in correctly.
+ */
+export declare function feedKindOf(action: FeedAction): "node" | "flow";
+/**
+ * Which `resource_type` the journal wrote an action against — a different question from
+ * `feedKindOf`, and the two answers disagree on purpose for exactly two actions (#767).
+ *
+ * A card about a finished run is a card about a **flow**: that is what it names, that is where it
+ * links, and `feedKindOf` says so. But the ROW it was written as carries `flow-run` and the run's
+ * id, so the query has to find it under a third kind and walk run → flow → folder to decide whether
+ * it may be seen.
+ *
+ * ⚠️ Derived here rather than written out beside the SQL. A second list that has to agree with this
+ * one is a second list too many — the same reason `NODE_ACTIONS` and `FLOW_ACTIONS` are filtered
+ * out of `FeedAction.options` instead of being typed again.
+ */
+export declare function feedResourceTypeOf(action: FeedAction): "node" | "flow" | "flow-run";
+export declare const FeedPathSegment: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strict>;
+export type FeedPathSegment = z.infer<typeof FeedPathSegment>;
+export declare const FeedEvent: z.ZodObject<{
+    id: z.ZodString;
+    actorId: z.ZodString;
+    action: z.ZodEnum<{
+        "node.create": "node.create";
+        "node.save": "node.save";
+        "node.append": "node.append";
+        "node.update": "node.update";
+        "node.archive": "node.archive";
+        "node.share": "node.share";
+        "node.revoke": "node.revoke";
+        "flows.create": "flows.create";
+        "flows.update": "flows.update";
+        "flows.archive": "flows.archive";
+        "flows.save": "flows.save";
+        "flows.publish": "flows.publish";
+        "flows.complete": "flows.complete";
+        "flows.cancel": "flows.cancel";
+        "flows.unpublish": "flows.unpublish";
+        "flows.share": "flows.share";
+        "flows.revoke": "flows.revoke";
+        "node.purge": "node.purge";
+        "flows.purge": "flows.purge";
+    }>;
+    resourceId: z.ZodString;
+    resourceTitle: z.ZodString;
+    path: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strict>>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    occurredAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type FeedEvent = z.infer<typeof FeedEvent>;
+export declare const FeedCursor: z.ZodString;
+export declare const FeedListRequest: z.ZodObject<{
+    actor: z.ZodOptional<z.ZodString>;
+    before: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type FeedListRequest = z.infer<typeof FeedListRequest>;
+export declare const FeedListResponse: z.ZodObject<{
+    events: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        actorId: z.ZodString;
+        action: z.ZodEnum<{
+            "node.create": "node.create";
+            "node.save": "node.save";
+            "node.append": "node.append";
+            "node.update": "node.update";
+            "node.archive": "node.archive";
+            "node.share": "node.share";
+            "node.revoke": "node.revoke";
+            "flows.create": "flows.create";
+            "flows.update": "flows.update";
+            "flows.archive": "flows.archive";
+            "flows.save": "flows.save";
+            "flows.publish": "flows.publish";
+            "flows.complete": "flows.complete";
+            "flows.cancel": "flows.cancel";
+            "flows.unpublish": "flows.unpublish";
+            "flows.share": "flows.share";
+            "flows.revoke": "flows.revoke";
+            "node.purge": "node.purge";
+            "flows.purge": "flows.purge";
+        }>;
+        resourceId: z.ZodString;
+        resourceTitle: z.ZodString;
+        path: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+        }, z.core.$strict>>;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        occurredAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type FeedListResponse = z.infer<typeof FeedListResponse>;

package/dist/contract/feed.js

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import { IntelId, IsoDateTime } from "./contract.js";
+// What a person did, in the words a person would use. This is a POSITIVE LIST and not the set of
+// actions the journal carries (#740).
+//
+// ⚠️ Two omissions are the point of the list, not an oversight. `node.version` is written by the
+// same batch as `node.save`, so admitting both would show every edit twice — and because this feed
+// does not group anything yet, twice means two cards. `node.link` and `node.import` are machine
+// traces of a save rather than something anybody did.
+//
+// ⚠️ And it stays a positive list. "Everything except" would silently admit whatever the next
+// migration starts writing, on a surface whose whole job is to be readable.
+export const FeedAction = z.enum([
+    "node.create",
+    "node.save",
+    "node.update",
+    "node.append",
+    "node.archive",
+    // ⚠️ The one event whose node no longer exists when it is read. Its visibility runs over the
+    // surviving folder, from `parentId` in the metadata, and its title comes from there too — the row
+    // it would have been read from is gone (#645).
+    "node.purge",
+    "node.share",
+    "node.revoke",
+    // The flow half (#763). Twelve kinds are written; these are the ones a person did rather than a
+    // machine bookkeeping step.
+    //
+    // ⚠️ **`flows.run` is deliberately NOT here, and its two siblings are** (#767, Jacks Entscheidung
+    // 2026-08-24). A run writes up to three events, and an agent runs often — without summarising,
+    // which #742 struck, twenty runs on one morning would be sixty cards and every human entry would
+    // lie buried under them.
+    //
+    // The END was chosen over the START, and not because it is cheaper: a finished run carries BOTH
+    // pieces — that it ran *and* how it went — while a start carries half of one. A run that hangs or
+    // fails looks exactly like one that sailed through, and that is the case somebody opens the feed
+    // for. What it costs is that a long run is invisible until it ends; that is the deliberate price
+    // of needing no merge over the run id, which is the only way a start-card could later be updated.
+    //
+    // ⚠️ These two are the only actions in this list written against `resource_type = 'flow-run'`,
+    // with the RUN's id — which is why `feedResourceTypeOf` exists below and why the query needs a
+    // third visibility walk (run → flow → folder) and a title read from the flow.
+    "flows.complete",
+    "flows.cancel",
+    "flows.create",
+    "flows.save",
+    "flows.update",
+    "flows.publish",
+    "flows.unpublish",
+    "flows.archive",
+    "flows.share",
+    "flows.revoke",
+    // ⚠️ The flow-side twin of `node.purge`, and it carries the same two consequences: its row is
+    // gone when the card is read, so both its visibility and its title come from the metadata of the
+    // event itself (#763, D73).
+    "flows.purge",
+]);
+/**
+ * What an entry is about. Derived from the action rather than carried separately: the two can then
+ * never disagree, and a reader that has to draw a flow differently from a document does not depend
+ * on a second field being filled in correctly.
+ */
+export function feedKindOf(action) {
+    return action.startsWith("flows.") ? "flow" : "node";
+}
+/**
+ * Which `resource_type` the journal wrote an action against — a different question from
+ * `feedKindOf`, and the two answers disagree on purpose for exactly two actions (#767).
+ *
+ * A card about a finished run is a card about a **flow**: that is what it names, that is where it
+ * links, and `feedKindOf` says so. But the ROW it was written as carries `flow-run` and the run's
+ * id, so the query has to find it under a third kind and walk run → flow → folder to decide whether
+ * it may be seen.
+ *
+ * ⚠️ Derived here rather than written out beside the SQL. A second list that has to agree with this
+ * one is a second list too many — the same reason `NODE_ACTIONS` and `FLOW_ACTIONS` are filtered
+ * out of `FeedAction.options` instead of being typed again.
+ */
+export function feedResourceTypeOf(action) {
+    if (action === "flows.complete" || action === "flows.cancel")
+        return "flow-run";
+    return feedKindOf(action);
+}
+// One step on the way down to the node, from the root. It carries the id as well as the title
+// because the surface links each step, and two folders may share a name.
+export const FeedPathSegment = z.strictObject({
+    id: IntelId,
+    title: z.string().min(1),
+});
+// One card's worth of journal.
+//
+// ⚠️ `resourceTitle` and `path` are read from `nodes` or `flows` at query time, so they are TODAY's
+// title and today's place — not the ones the thing had when the event happened. That is the right
+// answer for a feed (the reader wants to find it now) and the wrong one for an audit trail, which is
+// one more reason these are two doors and not one.
+//
+// ⚠️ The fields say `resource` and not `node` because half of them are not nodes (#763). Which half
+// is answered by `feedKindOf(action)` and by nothing on the card — a second field saying "flow"
+// beside an action that already says `flows.publish` is a second truth, and two truths disagree.
+//
+// `metadata` is whatever the write site recorded, untyped on purpose: a schema per action would
+// have to be kept in step with eleven write sites and would go stale in silence. What the surface
+// needs from it today is `sequence` on a `node.save`, which is the version number behind the card's
+// button.
+export const FeedEvent = z.strictObject({
+    id: IntelId,
+    actorId: z.string().min(1),
+    action: FeedAction,
+    resourceId: IntelId,
+    resourceTitle: z.string().min(1),
+    path: z.array(FeedPathSegment),
+    metadata: z.record(z.string(), z.unknown()),
+    occurredAt: IsoDateTime,
+});
+// ⚠️ Opaque BY CONTRACT, like the audit cursor and for the same reason: it is a PAIR
+// (`occurredAt`, `id`), and a timestamp alone cannot separate two events written in the same
+// millisecond — the normal case inside one batch. A reader continuing on the timestamp alone skips
+// the second one with no error and no log.
+//
+// ⚠️ It is deliberately NOT interchangeable with an audit cursor, although both encode the same
+// pair. The two doors walk the journal in opposite directions, so handing one's position to the
+// other reads on from the wrong end — and would look like a feed that suddenly starts at the
+// beginning of time rather than like a mistake. The encoding therefore carries its own marker and
+// the other door's cursor is refused.
+export const FeedCursor = z.string().min(1).max(400);
+export const FeedListRequest = z.strictObject({
+    actor: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Show only what this person or agent did. Omit it for everybody whose work you may see anyway."),
+    before: FeedCursor.optional().describe("Where to continue: the `nextCursor` of a previous answer, passed back unchanged. Omit it to start at the most recent event. Do not build one — it is opaque on purpose, and a cursor from `audit_list` is refused rather than followed backwards."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(30)
+        .describe("How many events to return at most. The answer may be shorter."),
+});
+// `nextCursor` is present exactly when another page may exist, and it is the cursor of the LAST
+// returned row.
+//
+// ⚠️ Present does not promise the next page is non-empty: the rows a reader may see can shrink
+// between calls. Treating "cursor present" as "there is more" is fair; treating an empty answer as
+// "you have reached the beginning of the journal" is not.
+export const FeedListResponse = z.strictObject({
+    events: z.array(FeedEvent),
+    nextCursor: FeedCursor.nullable(),
+});