@anchrd/intel-contract 0.25.0 → 0.27.0

package/dist/contract/feed.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+export declare const FeedAction: z.ZodEnum<{
+    "node.create": "node.create";
+    "node.save": "node.save";
+    "node.update": "node.update";
+    "node.append": "node.append";
+    "node.archive": "node.archive";
+    "node.share": "node.share";
+    "node.revoke": "node.revoke";
+}>;
+export type FeedAction = z.infer<typeof FeedAction>;
+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.update": "node.update";
+        "node.append": "node.append";
+        "node.archive": "node.archive";
+        "node.share": "node.share";
+        "node.revoke": "node.revoke";
+    }>;
+    nodeId: z.ZodString;
+    nodeTitle: 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.update": "node.update";
+            "node.append": "node.append";
+            "node.archive": "node.archive";
+            "node.share": "node.share";
+            "node.revoke": "node.revoke";
+        }>;
+        nodeId: z.ZodString;
+        nodeTitle: 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,84 @@
+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",
+    "node.share",
+    "node.revoke",
+]);
+// 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.
+//
+// ⚠️ `nodeTitle` and `path` are read from `nodes` at query time, so they are TODAY's title and
+// today's place — not the ones the node had when the event happened. That is the right answer for a
+// feed (the reader wants to find the thing now) and the wrong one for an audit trail, which is one
+// more reason these are two doors and not one.
+//
+// `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,
+    nodeId: IntelId,
+    nodeTitle: 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(),
+});

package/dist/contract/node.d.ts

@@ -120,9 +120,31 @@ export declare const PurgeNodePreviewInput: z.ZodObject<{
     nodeId: z.ZodString;
 }, z.core.$strict>;
 export type PurgeNodePreviewInput = z.infer<typeof PurgeNodePreviewInput>;
+/**
+ * ⚠️ **A count is not an answer before a deletion that cannot be undone** (D71, #733). `totalItems`
+ * alone reads as "82 items" for a folder holding somebody's whole memory, and `destructive.md` asks
+ * for the number to be named BEFORE the confirmation — one step more precise is the difference
+ * between a number and something a person can decide on.
+ *
+ * `items` is capped, and the cap is visible rather than silent: `totalItems` keeps counting past it,
+ * so a caller can always say "and 40 more". A list of ten thousand rows would be an answer nobody
+ * reads and a response nobody can render.
+ */
 export declare const PurgeNodePreview: z.ZodObject<{
     inboundLinks: z.ZodNumber;
     totalItems: z.ZodNumber;
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodUnion<readonly [z.ZodEnum<{
+            folder: "folder";
+            document: "document";
+            table: "table";
+            attachment: "attachment";
+            board: "board";
+            task: "task";
+        }>, z.ZodLiteral<"flow">]>;
+        title: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type PurgeNodePreview = z.infer<typeof PurgeNodePreview>;
 export declare const PurgeNodeResult: z.ZodObject<{

package/dist/contract/node.js

@@ -187,9 +187,27 @@ export const PurgeNodeInput = z.strictObject({
 export const PurgeNodePreviewInput = z.strictObject({
     nodeId: IntelId.describe("Archived node a purge would delete. Answers how many items would go with it and how many documents link to it from outside, and changes nothing. A node that is not archived is refused here for the same reason node_purge refuses it."),
 });
+/**
+ * ⚠️ **A count is not an answer before a deletion that cannot be undone** (D71, #733). `totalItems`
+ * alone reads as "82 items" for a folder holding somebody's whole memory, and `destructive.md` asks
+ * for the number to be named BEFORE the confirmation — one step more precise is the difference
+ * between a number and something a person can decide on.
+ *
+ * `items` is capped, and the cap is visible rather than silent: `totalItems` keeps counting past it,
+ * so a caller can always say "and 40 more". A list of ten thousand rows would be an answer nobody
+ * reads and a response nobody can render.
+ */
 export const PurgeNodePreview = z.strictObject({
     inboundLinks: z.number().int().nonnegative(),
     totalItems: z.number().int().positive(),
+    // ⚠️ `flow` beside the node kinds, because a flow filed in the folder goes with it and is counted
+    // in `totalItems`. Naming everything except flows would leave out the one thing the cascade had to
+    // be widened for (#733).
+    items: z.array(z.strictObject({
+        id: IntelId,
+        kind: z.union([NodeKind, z.literal("flow")]),
+        title: z.string(),
+    })),
 });
 // The title travels back because after this call nothing can look it up any more — not the row, not
 // a version, not the index. A caller that wants to say what it just deleted has this one chance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-contract",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -28,6 +28,10 @@
       "types": "./dist/contract/bundle.d.ts",
       "default": "./dist/contract/bundle.js"
     },
+    "./feed": {
+      "types": "./dist/contract/feed.d.ts",
+      "default": "./dist/contract/feed.js"
+    },
     "./flow": {
       "types": "./dist/contract/flow.d.ts",
       "default": "./dist/contract/flow.js"