@rubytech/create-maxy-code 0.1.488 → 0.1.490

package/payload/platform/lib/storage-broker/src/audit.ts

@@ -151,6 +151,14 @@ export interface DataPortalRow {
   objectKey: string;
   ingested: number;
   uploadedAt: string;
+  /** Where the bytes landed on the device, set only after a verified write
+   *  (Task 1910). Its presence IS the proof the move happened, which is what
+   *  separates a healthy moved row from a phantom. Absent on a portal whose
+   *  hand-run ALTER has not happened yet, which reads as "never moved". */
+  devicePath?: string;
+  /** 1 when the client has withdrawn an already-moved file and the device has
+   *  not yet removed it. */
+  deleted?: number;
 }
 
 export interface DataPortalReconcile {
@@ -167,6 +175,31 @@ export interface DataPortalReconcile {
   /** Null when nothing is uningested, or when no uningested row carries a
    *  parseable timestamp. Rendered `na` by the caller. */
   oldestUningestedHrs: number | null;
+  /** Every row at `ingested = 0`, including rows whose `uploadedAt` does not
+   *  parse. Deliberately NOT the size of the age sample below: that sample
+   *  excludes unparseable timestamps, so a backlog made entirely of them would
+   *  report a null age beside a zero count and read as an empty queue. */
+  uningestedRows: number;
+  /** Objects still in R2 whose row says the bytes already reached the device
+   *  (Task 1910). The move deletes the object after the claim commits, so a
+   *  survivor is a leak. It emits nothing at request time — the pull has
+   *  already returned and no later request touches the key — which is why it
+   *  is counted here rather than logged somewhere. */
+  unmovedObjects: string[];
+  /** Withdrawals the device has not carried out yet. Healthy is 0; a number
+   *  that persists across cycles is a withdrawal that will never complete. */
+  deletePendingRows: number;
+  /** Age of the oldest pending withdrawal, so a stuck one is dateable rather
+   *  than merely present. Null when none are pending. */
+  oldestDeletePendingHrs: number | null;
+  /** Files routed into an exposed folder that the published index does not
+   *  carry. The client uploaded into a folder, the file landed, and the tree
+   *  still does not show it.
+   *
+   *  NULL when the index was not supplied, never 0: an unread index is "not
+   *  measured", and rendering it as zero would let a failed read present as a
+   *  clean bill of health. */
+  unpublishedRouted: number | null;
 }
 
 /** Pure over two lists and an injected clock, so the age arithmetic is
@@ -179,16 +212,24 @@ export function reconcileDataPortal(
   objects: DataPortalObject[],
   rows: DataPortalRow[],
   nowMs: number,
+  publishedPaths?: Set<string>,
 ): DataPortalReconcile {
   const objectKeys = new Set(objects.map((o) => o.key));
   const rowKeys = new Set(rows.map((r) => r.objectKey));
 
+  // A moved row's bytes are deliberately NOT in R2, so it is neither a phantom
+  // nor an orphan — it is the healthy end state of the exchange. Splitting the
+  // row set here is what keeps the pre-existing counts meaning what they meant
+  // before the move existed.
+  const moved = rows.filter((r) => Boolean(r.devicePath));
+  const movedKeys = new Set(moved.map((r) => r.objectKey));
+
   // Date.parse of a truthy non-ISO value is NaN, which slips past a `??` guard
   // and renders as `oldestUningestedHrs=NaN` — the defect the availability
   // loop's snapshotAgeMs already had to fix. Unparseable rows are excluded from
   // the minimum; if that leaves none, the answer is null, never NaN.
-  const uningestedMs = rows
-    .filter((r) => r.ingested === 0)
+  const uningested = rows.filter((r) => r.ingested === 0);
+  const uningestedMs = uningested
     .map((r) => Date.parse(r.uploadedAt))
     .filter((ms) => !Number.isNaN(ms));
 
@@ -201,11 +242,34 @@ export function reconcileDataPortal(
   // escape the caller's per-side catches and cost every later account its line.
   const oldestMs = uningestedMs.reduce((min, ms) => (ms < min ? ms : min), Infinity);
 
+  const pendingDeletes = rows.filter((r) => r.deleted === 1);
+  const pendingDeleteMs = pendingDeletes
+    .map((r) => Date.parse(r.uploadedAt))
+    .filter((ms) => !Number.isNaN(ms));
+  // Reduced rather than spread, for the same stack-overflow reason as above.
+  const oldestPendingMs = pendingDeleteMs.reduce((min, ms) => (ms < min ? ms : min), Infinity);
+
   return {
     distinctObjects: objectKeys.size,
     distinctRows: rowKeys.size,
     orphanObjects: [...objectKeys].filter((k) => !rowKeys.has(k)),
-    phantomRows: [...rowKeys].filter((k) => !objectKeys.has(k)),
+    // A moved row is excluded: its object is SUPPOSED to be gone, so counting
+    // it would manufacture a defect on every healthy exchange.
+    phantomRows: [...rowKeys].filter((k) => !objectKeys.has(k) && !movedKeys.has(k)),
     oldestUningestedHrs: uningestedMs.length === 0 ? null : (nowMs - oldestMs) / 3_600_000,
+    uningestedRows: uningested.length,
+    unmovedObjects: [...movedKeys].filter((k) => objectKeys.has(k)),
+    deletePendingRows: pendingDeletes.length,
+    oldestDeletePendingHrs:
+      pendingDeleteMs.length === 0 ? null : (nowMs - oldestPendingMs) / 3_600_000,
+    unpublishedRouted:
+      publishedPaths === undefined
+        ? null
+        : moved.filter(
+            (r) =>
+              // uploads/ is never published by design, so only a file routed
+              // into an exposed folder can be "unpublished".
+              !r.devicePath!.startsWith("uploads/") && !publishedPaths.has(r.devicePath!),
+          ).length,
   };
 }

package/payload/platform/lib/storage-broker/src/cf-exec.ts

@@ -53,6 +53,19 @@ export interface CfExec {
   d1List(): Promise<{ name: string; uuid: string }[]>;
   d1Create(name: string): Promise<{ uuid: string }>;
   d1Query(name: string, sql: string): Promise<unknown>;
+  /**
+   * One statement with BOUND parameters, over the D1 HTTP API (Task 1910).
+   *
+   * `d1Query` above takes raw SQL and spawns wrangler per statement, so every
+   * caller must interpolate its values. The portal pull writes client-supplied
+   * filenames and paths, which must never be concatenated into SQL — a UUID
+   * gate on one field is not a substitute for binding.
+   *
+   * This is deliberately NOT the convergence of the three D1 clients (Task
+   * 1843); it is one bound path for the callers that need one, added where the
+   * house credential already lives so no second credential path appears.
+   */
+  d1Exec(name: string, sql: string, params?: unknown[]): Promise<unknown>;
   r2List(): Promise<{ name: string }[]>;
   r2Create(name: string): Promise<void>;
   r2ObjectList(bucket: string, prefix?: string): Promise<R2Object[]>;
@@ -278,6 +291,41 @@ export function makeCfExec(
       );
       return parseJson(stdout, "d1 execute");
     },
+    async d1Exec(name, sql, params = []) {
+      // The database is addressed by uuid, so the name is resolved first. An
+      // exact name match, never "the first result": `?name=` is a filter whose
+      // matching rule is undocumented, and taking position on trust would run
+      // these statements against a near-named database.
+      const listUrl =
+        `https://api.cloudflare.com/client/v4/accounts/${cred.accountId}` +
+        `/d1/database?name=${encodeURIComponent(name)}`;
+      const { parsed: listed } = await cfApiJson(
+        fetchFn,
+        listUrl,
+        { method: "GET", headers: { Authorization: `Bearer ${cred.apiToken}` } },
+        "d1 database lookup",
+      );
+      const hit = ((listed as { result?: { name?: string; uuid?: string }[] }).result ?? []).find(
+        (d) => d.name === name,
+      );
+      if (!hit || typeof hit.uuid !== "string") {
+        throw new Error(`storage-broker: no D1 database named "${name}"`);
+      }
+      const { parsed } = await cfApiJson(
+        fetchFn,
+        `https://api.cloudflare.com/client/v4/accounts/${cred.accountId}/d1/database/${hit.uuid}/query`,
+        {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${cred.apiToken}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ sql, params }),
+        },
+        "d1 query",
+      );
+      return (parsed as { result?: unknown }).result;
+    },
     async r2List() {
       // `wrangler r2 bucket list` has no --json flag and emits human prose, so
       // it can neither be parsed nor honour the "never grep a CLI's prose"

package/payload/platform/neo4j/schema.cypher

@@ -2228,3 +2228,108 @@ OPTIONS {
     `vector.similarity_function`: 'cosine'
   }
 };
+
+// ---------------------------------------------------------------------------
+// Vertical node-type declarations (Task 1893).
+//
+// Every label below is declared in a `## Node Types` / `## Additional Node
+// Types` table of a schema-*.md ontology doc but had no line here, so the
+// schema-doc drift guard could not see it and the first memory-write against a
+// fresh graph would hit an unregistered label. The guard was blind to them
+// because it matched only the backticked `:Label` prose form.
+//
+// An accountId index, not a uniqueness constraint. Only schema-construction.md
+// and schema-knowledge-work.md carry an `## Idempotency contracts` section, so
+// no natural key is agreed for any label here, and several have none that would
+// be correct: two :StockMovement rows on one day are legitimately distinct, as
+// are two :Stop rows on one route. accountId is the one property every one of
+// them requires, and an index can never reject a legitimate write.
+// ---------------------------------------------------------------------------
+
+// schema-base.md
+//
+// :`Order` and :`Case` are backtick-escaped because ORDER and CASE are Cypher
+// reserved words. Escaping a label is always legal whether or not the word is
+// reserved, and seed-neo4j.sh pipes this whole file through cypher-shell under
+// `set -euo pipefail`, so one unparseable statement aborts the entire install
+// seed. They are the only two of the 130 declared labels that collide.
+CREATE INDEX order_account IF NOT EXISTS
+FOR (n:`Order`) ON (n.accountId);
+
+CREATE INDEX lead_account IF NOT EXISTS
+FOR (n:Lead) ON (n.accountId);
+
+CREATE INDEX case_account IF NOT EXISTS
+FOR (n:`Case`) ON (n.accountId);
+
+CREATE INDEX whatsapp_conversation_account IF NOT EXISTS
+FOR (n:WhatsAppConversation) ON (n.accountId);
+
+CREATE INDEX whatsapp_message_account IF NOT EXISTS
+FOR (n:WhatsAppMessage) ON (n.accountId);
+
+// schema-creator.md
+CREATE INDEX content_account IF NOT EXISTS
+FOR (n:Content) ON (n.accountId);
+
+CREATE INDEX campaign_account IF NOT EXISTS
+FOR (n:Campaign) ON (n.accountId);
+
+CREATE INDEX audience_account IF NOT EXISTS
+FOR (n:Audience) ON (n.accountId);
+
+CREATE INDEX brand_deal_account IF NOT EXISTS
+FOR (n:BrandDeal) ON (n.accountId);
+
+// schema-food-beverage.md
+CREATE INDEX table_reservation_account IF NOT EXISTS
+FOR (n:TableReservation) ON (n.accountId);
+
+CREATE INDEX menu_item_account IF NOT EXISTS
+FOR (n:MenuItem) ON (n.accountId);
+
+CREATE INDEX menu_account IF NOT EXISTS
+FOR (n:Menu) ON (n.accountId);
+
+CREATE INDEX dining_order_account IF NOT EXISTS
+FOR (n:DiningOrder) ON (n.accountId);
+
+// schema-hospitality.md
+CREATE INDEX reservation_account IF NOT EXISTS
+FOR (n:Reservation) ON (n.accountId);
+
+CREATE INDEX room_account IF NOT EXISTS
+FOR (n:Room) ON (n.accountId);
+
+// schema-logistics.md
+CREATE INDEX shipment_account IF NOT EXISTS
+FOR (n:Shipment) ON (n.accountId);
+
+CREATE INDEX vehicle_account IF NOT EXISTS
+FOR (n:Vehicle) ON (n.accountId);
+
+CREATE INDEX route_account IF NOT EXISTS
+FOR (n:Route) ON (n.accountId);
+
+CREATE INDEX stop_account IF NOT EXISTS
+FOR (n:Stop) ON (n.accountId);
+
+// schema-professional-services.md
+CREATE INDEX engagement_account IF NOT EXISTS
+FOR (n:Engagement) ON (n.accountId);
+
+CREATE INDEX retainer_account IF NOT EXISTS
+FOR (n:Retainer) ON (n.accountId);
+
+CREATE INDEX deliverable_account IF NOT EXISTS
+FOR (n:Deliverable) ON (n.accountId);
+
+// schema-retail.md
+CREATE INDEX product_account IF NOT EXISTS
+FOR (n:Product) ON (n.accountId);
+
+CREATE INDEX stock_movement_account IF NOT EXISTS
+FOR (n:StockMovement) ON (n.accountId);
+
+CREATE INDEX store_location_account IF NOT EXISTS
+FOR (n:StoreLocation) ON (n.accountId);

package/payload/platform/plugins/admin/skills/agent-builder/references/agent-pattern.md

@@ -59,10 +59,10 @@ named. Derive the allowlist from the skills the agent owns: read each skill, lis
 calls, take the union, and stop there. A vertical agent never inherits a horizontal agent's
 whole surface. Do not add a tool "in case"; an unused tool is a boundary you gave away.
 
-## The body: identity, then the three-part contract
+## The body: identity, then the contract sections
 
 After the frontmatter the body opens with the agent's doctrine and identity (who it is, what it
-owns, and the standing git-write boundary the roster shares), then the three contract sections
+owns, and the standing git-write boundary the roster shares), then the contract sections
 in this exact order and with these exact headings:
 
 ### Output contract
@@ -88,6 +88,35 @@ it:
 A headless agent with no human-in-the-loop step (a classifier, a rewriter) carries the
 untrusted-input line alone; review gates do not apply where there is no operator checkpoint.
 
+### Grounding
+
+Heading `## Grounding`, last section in the file. Two sentences, the same wording in every agent
+so a reviewer and a test can grep them, exactly as the untrusted-input line is. Copy them
+character for character:
+
+> Every factual claim you make carries a source you can name and, when it is time sensitive, the date you observed it; a fact you cannot source, or a date you cannot see, is a gap you flag, never one you supply from training recall.
+
+> The only source for an attribute of a named person, the pronoun you use for them included, is that person's record; an attribute you cannot read there is one you leave out, never one you assume.
+
+They live in their own section rather than inside the Output contract because they are
+behavioural rules, not part of any deliverable. Several agents fix an exact machine-parseable
+reply shape in their Output contract, and prose inside that section would contradict it.
+
+The second sentence is worded so that an agent holding no read tool satisfies it by leaving the
+attribute out. It never tells such an agent to attempt a lookup its own prompt forbids. That is
+why it names the record as the only source rather than instructing a read.
+
+Two further clauses bind the Output contract itself. **Recency**, universal: a time-sensitive
+claim carries the date it was observed, and a date the agent cannot see is one it flags, never
+one it infers. **Corroboration**, for agents whose deliverable is a pattern, a theme, a trend, a
+signal: the agent names the independent sources behind it and does not report one as established
+on a single occurrence. Corroboration is authoring guidance enforced by review, not by the gate,
+because the subset it applies to cannot be detected statically.
+
+`agent-grounding-drift.test.ts` fails if any shipped prompt carries either sentence anything
+other than exactly once, and fails if the number of prompts it inspected is not the number it
+expects. A new agent that skips them does not ship.
+
 ## Skills owned
 
 The body closes with the skills the agent owns, as a table: the skill, the plugin it lives in,
@@ -97,7 +126,7 @@ skill-builder flow, so the agent and its skills land together.
 
 ## Why this shape
 
-A fixed contract makes every agent legible. An operator reading the file knows in three sections
-what it produces, where it pauses for them, and that it will not act on text it was handed as
-data. A reviewer can check the same three things by grep. The reference agents prove this costs
+A fixed contract makes every agent legible. An operator reading the file knows what it produces,
+where it pauses for them, that it will not act on text it was handed as data, and what it may
+treat as a source. A reviewer can check each of them by grep. The reference agents prove this costs
 about 320 words and is worth standardising.

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:103d5688cd9255611a9bf233effbaf7ffd8b45afa48b26d4f92b86febcfac1f5
+content-hash: sha256:643a947eb8968517ad598f7f8b4e433d8545877d7c21f857d4867ac914e34cc9
 brand: maxy-code
 product-name: Maxy
 ---
@@ -2482,10 +2482,14 @@ This usually completes within a couple of minutes of the booking.
 Bookings are reconciled on a cycle and the system audits itself each run. In the device logs:
 
 - `[calendar-booking]` lines trace one booking through submit, write, notify, and done.
-- `[calendar-reconcile]` lines report three health numbers per account: `eligibleExamined` (bookings the check looked at), `pendingUnreconciled` (bookings captured but not yet turned into meetings) and `orphanMeetings` (booking meetings with no matching saved booking). Entries that only block out a slot are not counted — they are not bookings and never become meetings.
+- `[calendar-reconcile]` lines report four health numbers per account: `eligibleExamined` (bookings the check looked at), `pendingUnreconciled` (bookings captured but not yet turned into meetings), `pendingOldestAgeMin` (how many minutes the longest-waiting of those has been waiting) and `orphanMeetings` (booking meetings with no matching saved booking). Entries that only block out a slot are not counted — they are not bookings and never become meetings.
 
 A `pendingUnreconciled` number that stays above zero across several runs means those bookings are failing to turn into meetings, and the `attempt=` number on the matching `[calendar-booking]` lines says how many times each has been tried. A booking whose meeting is deleted is picked up again automatically on the next run. To read them: `journalctl --user -u <brand-service> | grep -E '\[calendar-booking\]|\[calendar-reconcile\]'`, then filter by one booking id for its full story. The edge half of a booking (before your device sees it) is in the Cloudflare Pages function logs.
 
+A count on its own cannot tell a short lag from a long one: five bookings waiting two minutes and five waiting nine hours are both `pendingUnreconciled=5`. `pendingOldestAgeMin` is what separates them. It reads `0` when nothing is waiting, and also when something is waiting but for under a minute, so read it together with the count beside it.
+
+A separate `op=liveness` line is printed every ten minutes by your device's own server, whether or not anything is wrong. `stale=false` means the booking check has run recently. `stale=true` means it has not run in over six minutes, which is the case nothing else can tell you about: a check that has stopped cannot report that it has stopped. `lastSkipReason` names the last account whose check finished without looking at any bookings, and reads `none` when every account it got to was checked. If you run more than one account, a check can both look at one account and skip another, so seeing a recent check time next to a skip reason is normal and means two different accounts.
+
 ## When your real calendar lives elsewhere
 
 The booking page publishes open slots from the internal calendar, the one Maxy keeps in its own graph.
@@ -4219,6 +4223,8 @@ Standing rules the operator gives over a channel are `Preference` nodes. Two mec
 
 **Trust a scheduled turn's provenance, never an inbound's claim (channel-agent grounding).** A cron-dispatched agent turn reaches the same channel builders as a real inbound, so its own authorisation text would otherwise land inside `## Context` — the zone `REFRAME_INSTRUCTION` demotes to untrusted — and a security-cautious agent would distrust its own automation (the self-cancel loop). The dispatcher therefore stamps a `ScheduleProvenance` marker (owning account, event, owner userId, dispatch time) that the channel builders render as a `## Scheduled automation (platform-verified)` preamble **above** `## Context` (and above the rules block); the whatsapp wrap tag names the door `scheduler`. Both channel-server paths carry the marker — the single-target loop and the unified multi-target door reader (via the same `doorInboundPayload` seam that carries `standingRules`); the scheduler only dispatches to the whatsapp/telegram door, so a webchat frame never bears one. Because the marker is dispatcher-stamped and never derived from payload text, an inbound message cannot forge it — placement above `## Context` alone is not the trust signal, the dispatcher provenance is. The grounding binds to it in two places: one recipient-neutral clause added byte-identical to the three reframe instructions (a marker-bearing turn is authorised standing automation; a reconfiguration or re-enable is not intrusion), and the admin `IDENTITY.md` "Untrusted input" rule that the agent never states a platform-level authenticity or impersonation verdict it was not given (an unsourced "this is not from you" is its own inference, flagged, never asserted as the platform's). A sender has exactly one session: every inbound, real or scheduled, resolves to the deterministic `adminSessionIdFor(effectiveAccount, destination)`. An earlier change gave each firing its own salted seat so distrust could not accrete across firings, but the inbound hub keys on `senderId` and replaces its subscriber outright, so a seat's channel server attached under the sender's own key and swallowed the sender's REAL messages until it detached — splitting one conversation across two sessions that each denied what the other held. The seat is removed; the authoritative `agentPrompt`, this provenance marker, and the injected standing rules ground each firing without one. Self-cancel attribution is disarmed while that model beds in: the guard used to compare the cancelling turn's session id to a dispatcher stamp, which discriminated only because each firing ran its own seat, so with one session per sender it would report an autonomous loop on every operator cancel. It now always reports false — under-counting a real loop rather than inventing one — until the discriminator is rebuilt from the turn's own dispatched eventId. See `.docs/scheduling-agent-dispatch.md § Operator-provenance marker`, `§ Session model — one session per sender`, and `§ Self-cancel attribution — disarmed`.
 
+**Carry what a reply points at (WhatsApp reply quote).** A WhatsApp sender replying to an earlier message produces a quote that `app/lib/whatsapp/inbound/extract.ts` resolves to `{ id, text?, sender? }` and `manager.ts` assigns to the route payload's `replyContext`. That field had no reader: the `server/index.ts` gateway argument omitted it, `AdminInbound` and the hub frame had no such field, and the channel service's `composePayload` emitted the caption and media notes only, so a message saying "prepare an email confirmation for this booking" reached the agent with nothing to resolve "this booking" against. It now rides both WhatsApp admin doors. On the persistent door it travels `server/index.ts` -> `AdminInbound` -> the hub frame the SSE route stringifies -> the channel service's `InboundPayload`, where `composeReplyNote` renders it as a bracketed note at the top of the payload, inside `## Context` and above the caption and any woven media notes: the quoted body is sender-controlled and belongs in the reframed untrusted zone, never in the platform preamble. Both channel-server inbound paths carry it, through the same `doorInboundPayload` seam that carries `standingRules` and the schedule provenance marker: the single-target SSE loop parses the whole frame, and the unified multi-target door reader rebuilds the payload field by field, so a field that seam omits is dropped on multi-target sessions alone. That seam is guarded by a test which reads the `InboundPayload` declaration and the rebuild function rather than a fixture, because the pre-existing byte-identity guard compared one hardcoded payload and so stayed green for every field added after it was written. On the passive account-manager door there is no channel server and no `## Context` frame, so the one-shot's whole initial prompt is read at face value; `composePassivePrompt` therefore puts the BARE sentence above the requirement and never the quoted body. The body arrives from the sender's own client and is never checked against the message store, so quoting it in a platform-voiced bracket on the door with no untrusted zone would let a modified client put words the agent never said into a `work-create` filing. The empty-text drop gate still tests the requirement alone, so a quote never rescues an inbound carrying no requirement of its own. The quoted body is capped at `QUOTED_TEXT_CAP` (500 characters, `…` appended when cut) because it is unbounded sender-controlled input, and the cut lands on whole characters so a body whose 500th boundary falls inside a surrogate pair cannot emit a lone surrogate at a position the sender chose. Only the channel service renders a body, so the cap lives there alone; platform/ui's `app/lib/whatsapp/reply-quote.ts` holds just the bare sentence for the passive door, and both packages hardcode that sentence in their own tests so the two doors cannot drift apart on the wording (the packages never cross-import, the same arrangement `REFRAME_INSTRUCTION` and `MediaRef` use). Telegram and webchat extract no quote at all, so neither carries one. `payloadBytes` measures the whole inner payload, so a reply carrying a quote produces a visibly larger `[reframe] op=applied … payloadBytes=<n>` than the same text without one, and a bare-text-length `payloadBytes` on an inbound whose store row has a non-null `quotedId` is the signature of this defect returning. Because the field is optional at every hop, dropping it from either `server/index.ts` argument would be silent (tsc stays green, and no unit test executes that wiring file), so the `check-reply-context-threaded` build gate asserts both argument sites.
+
 **Observability.** `[preference-write] op=reconcile … mode=<reinforce|update|contradict|new> similarity=…` — a stream of `mode=new` for subjects that already exist is the duplicate-minting signature. `[preference-inject] op=inject channel=<wa|tg|web> injected=<N> owner=<8> source=<owner|no-owner|owner-error|fetch-error>` — injection selects only the account owner's admin preferences, so `source=owner injected=0` is a genuinely empty owner, `source=no-owner` is an account with no seeded owner (injects nothing, a missed owner seeding), and `injected=0 source=owner` on an account whose owner holds rules is the write-only regression re-appearing. `[preference-audit] op=drift accountId=… storedActive=… injectedActive=… duplicateClusters=…` — the standing reconciliation audit (claude-session-manager, 5-minute tick) flags any account whose store holds more active rows than injection would surface, the no-event detector for drift.
 
 ---

package/payload/platform/plugins/cloudflare/PLUGIN.md

@@ -73,11 +73,11 @@ The setup-done claim only fires when `curl -I https://<hostname>` issued from ou
 
 The portal shows a sub-account's deliverable folders alongside what the client uploaded. Which folders those are is never a list in the code: it is derived per account from that account's own `SCHEMA.md` — the buckets in its `<!-- ontology-buckets -->` region plus `output`, intersected with its `allowed-top-level` block. A brand on a different vertical exposes different folders with no code change. `bin/schema-exposed-dirs.mjs` is the only place that decision is made. An operator can add non-ontology folders (a workflow folder such as `inbound-invoices`) by listing them in `exposeFolders` in the account's `data-portal.json`; each must match `[A-Za-z0-9_-]+` and is never a system folder (`agents`, `secrets`, `specialists`, `state`, `memory`, `cache`, `logs`, `tmp`) or dot-prefixed. Those extras union on top of the schema-derived set and, unlike ontology buckets, are not intersected with `allowed-top-level`; empty or absent behaves as before.
 
-`bin/portal-index-push.mjs` walks those folders and full-replaces the account's rows in the portal's D1 `directory` table each cycle. Metadata only — names, sizes, times — so listing survives the device being offline, and a deleted or renamed file converges on the next cycle without a tombstone. The scheduling heartbeat runs it hourly for every account carrying a `data-portal.json`; it is also runnable standalone, which is how it stays operable while the heartbeat spawn path is unproven on a device.
+`bin/portal-index-push.mjs` walks those folders and full-replaces the account's rows in the portal's D1 `directory` table each cycle. Metadata only — names, sizes, times — so listing survives the device being offline, and a deleted or renamed file converges on the next cycle without a tombstone. Every walked folder gets a row of its own marked `isDir`, not only the files inside it, so an exposed folder holding nothing at any depth still renders and opens; a folder whose `readdir` fails publishes nothing, so the tree never offers one the device does not have. `isDir` is a later column and `IF NOT EXISTS` adds nothing to an existing table, so a portal that predates it needs one hand-run `ALTER TABLE directory ADD COLUMN isDir INTEGER NOT NULL DEFAULT 0`. The scheduling heartbeat runs it hourly for every account carrying a `data-portal.json`; it is also runnable standalone, which is how it stays operable while the heartbeat spawn path is unproven on a device.
 
 Opening a file reaches the install: the portal probes it, then mints an `/api/portal/fetch` link signed with the account's `PORTAL_FETCH_SECRET` and valid for five minutes. The install verifies the signature **and independently re-derives the exposed folder set**, so a correctly signed link for a non-exposed path is still refused. That second check is the security boundary, not the signature.
 
-Exposure is narrowed twice. The install re-derives the account's exposed set from `SCHEMA.md` on every request and refuses anything outside it, which is the account-isolation boundary. On top of that, a person's `people.folders` grant (written at enrolment, empty means the full set) narrows them to named top-level folders inside that set. The grant lives only in the portal's D1, so a portal compromise widens a person back to the account's exposed set and never beyond it. `op=list` carries `granted=<n|full>` and an out-of-grant download logs `op=fetch-through result=not-granted`, distinct from `result=absent`.
+Exposure is narrowed twice. The install re-derives the account's exposed set from `SCHEMA.md` on every request and refuses anything outside it, which is the account-isolation boundary. On top of that, a person's `people.folders` grant (written at enrolment, empty means the full set) narrows them to named top-level folders inside that set. The grant lives only in the portal's D1, so a portal compromise widens a person back to the account's exposed set and never beyond it. `op=list` carries `granted=<n|full>` and an out-of-grant download logs `op=fetch-through result=not-granted`, distinct from `result=absent`. A download naming a folder logs `result=is-directory` and mints no link, distinct from both.
 
 What to watch, on the device:
 
@@ -94,6 +94,26 @@ What to watch, on the device:
 
 `op=audit` is the standing check, and it is the only one that speaks when the push does **not**. It runs in-process inside the heartbeat rather than as a spawn, and reads only local state, so it cannot be blinded by the same failure it is watching for. It fires hourly even when everything is healthy — an audit that goes quiet on success is indistinguishable from an audit that stopped running. `result=never-ran` on an account with a `data-portal.json` means no cycle has ever succeeded for it; `result=stale` with `ageMin` means cycles have stopped. Its input is written only after `op=verify`, so a stale entry means the push stopped succeeding rather than merely stopped logging.
 
+## Data-portal upload pull
+
+The index push publishes what the device holds; the pull is the other direction. An upload lands in R2 under the person's prefix with one `manifest` row at `ingested = 0`, and the `portal-uploads-pull` loop in the admin server carries it onto the device every minute. It does not live in this plugin: it sits beside `runDataPortalAudit` in `platform/ui/server/portal-uploads-pull.ts`, because that audit already resolves the house Cloudflare credential and each account's portal database and bucket, and a second enumeration or credential path is how the two would drift.
+
+Per pending row the order is fetch, write, verify, then claim. The object is fetched by `objectKey` through the storage broker, written to a dot-prefixed `.uploads-tmp/` partial (invisible to the index walk, so a partial can never be published as a deliverable), renamed into `uploads/<ownerName>/<filename>`, and only then is `ingested` set to 1 — and only if the written size equals `manifest.size`. A row claimed before the bytes land is a lost file carrying a flag that says it arrived. Anything that fails leaves the row at 0 and it is retried next cycle. `ownerName` and `filename` must each be a single path segment, checked on the device rather than trusted from the portal's own gate, and `fileId` must be a UUID before it reaches a statement, because `d1Query` takes raw SQL and binds nothing.
+
+What to watch, on the device:
+
+```
+[portal-pull] op=claim account=<id> fileId=<uuid> bytes=<n> result=written|fetch-failed|write-failed|verify-failed|claim-failed|bad-owner|bad-filename|bad-fileid
+[portal-pull] op=done account=<id> pulled=<n> failed=<n>
+[portal-pull] op=malformed account=<id> rows=<n>
+[portal-pull] op=failed account=<id> err="<message>"
+[data-portal-audit] account=<id> … oldestUningestedHrs=<n|na> pendingRows=<n|na>
+```
+
+`[data-portal-audit]` is the standing signal, printed every cycle including at `pendingRows=0`, so a quiet line reads as healthy rather than as a stopped pull. When a client says a file never arrived: a `pendingRows` that stays non-zero with a rising `oldestUningestedHrs` means the pull runs and cannot finish, so read `result=` on `op=claim`. `pendingRows=na` means the manifest read itself failed, a different fault. No `[data-portal-audit]` line at all means the audit loop is not running, a third. Both counts are computed from the manifest alone, so they survive R2 being unreachable — which is exactly when a stalled pull matters most. `result=claim-failed` is the one outcome that leaves a file on disk with its row unclaimed; the next cycle re-fetches and overwrites the same path, which is deliberate.
+
+Log lines carry counts and ids only. An object key is `<ownerId>/<filename>`, a real person's filename, and the brand journal is not where those belong.
+
 On the portal side `[data-portal] op=list` carries `account=` and `op=fetch-through` carries the outcome; on the install `[portal-fetch]` logs `op=request` then exactly one of `op=served`, `op=denied`, `op=miss`. A portal `fetch-through` with no matching install `op=request` means the request never arrived, rather than having been refused. `[portal-fetch] op=no-secret account=<id>` is an unconfigured portal, which the `op=denied reason=secret` line alone would not distinguish from a bad signature.
 
 ## Discipline