@tpsdev-ai/flair 0.20.1 → 0.22.0

package/schemas/federation.graphql

@@ -39,6 +39,18 @@ type Peer @table(database: "flair") @export {
   updatedAt: String
 }
 
+# Anti-replay nonce store (federation-edge-hardening slice 4).
+# Persists nonces recorded by verifyBodySignatureFresh (federation-crypto.ts)
+# so an instance restart doesn't wipe recently-seen nonces — closes the
+# ±30s freshness-window replay gap a restart would otherwise reopen. Nonces
+# are already globally unique (128-bit random, generated per request by
+# signBodyFresh), so the nonce string itself is the primary key — no scope
+# prefix needed. Internal bookkeeping only: never served, never replicated.
+type Nonce @table(database: "flair") {
+  id: ID @primaryKey               # the nonce string (base64url, 128-bit random)
+  seenAt: Int! @indexed            # ms-epoch when first recorded — eviction cutoff
+}
+
 # Sync log — audit trail for federation operations.
 type SyncLog @table(database: "flair") {
   id: ID @primaryKey

package/schemas/memory.graphql

@@ -5,6 +5,16 @@ type Memory @table(database: "flair") {
   contentHash: String @indexed
   visibility: String
   embedding: [Float] @indexed(type: "HNSW")
+  embeddingModel: String @indexed  # ops-1l18: previously written (resources/Memory.ts stamps every
+                               # write) but never DECLARED in this schema, so it was storable but not
+                               # queryable — Harper's Table.search({conditions}) rejects a condition on
+                               # an undeclared attribute ("X is not a defined attribute"), which the
+                               # zero-touch migration runner's bounded detect()/countPending()/run()
+                               # queries (resources/migrations/embedding-stamp.ts: `embeddingModel
+                               # not_equal <current>`) need in order to stay O(1)-bounded rather than a
+                               # full-corpus scan on every boot. Purely additive — existing rows already
+                               # carry this value on disk; declaring it queryable changes nothing about
+                               # what's written or how embeddings/prefixes behave (#689's gate untouched).
   tags: [String] @indexed
   durability: String @indexed
   source: String
@@ -13,6 +23,18 @@ type Memory @table(database: "flair") {
   expiresAt: String @indexed
   retrievalCount: Int
   lastRetrieved: String
+  usageCount: Int              # flair#683: verified-USE signal, distinct from retrievalCount (a
+                               # search HIT). Additive/nullable — absent reads as 0, existing rows
+                               # unaffected. NEVER auto-incremented on search/retrieval; the ONLY
+                               # writer is the dedicated usage-feedback endpoint (resources/
+                               # MemoryUsage.ts), which does a targeted patchRecord increment on
+                               # this field alone (never through Memory.put() — see that
+                               # resource's module doc for why: usage-feedback writes to ANOTHER
+                               # agent's memory, and Memory's ownership check would 403 every
+                               # legit call). Drives usageBoost in resources/scoring.ts, which
+                               # replaces retrievalBoost in compositeScore (retrievalCount was the
+                               # contaminated "retrieval counted as usage" signal root-caused in
+                               # flair#623).
   promotionStatus: String   # null | "pending" | "approved" | "rejected"
   promotedAt: String
   promotedBy: String        # authenticated agentId who approved
@@ -31,11 +53,36 @@ type Memory @table(database: "flair") {
   validFrom: String @indexed   # ISO timestamp — when this fact became true
   validTo: String @indexed     # ISO timestamp — when this fact stopped being true (null = still valid)
   _safetyFlags: [String]       # content safety flags from scanContent()
+  provenance: String           # JSON blob (memory-provenance slice 1): { v, verified: { agentId, timestamp }, claimed?: { model } }
+                               # Nullable by design — existing rows read back provenance = null, unchanged behavior (clean-upgrade-path gate).
+                               # Same idiom as Soul.metadata below. Stamped server-side in resources/Memory.ts; never client-writable.
+  originatorInstanceId: String @indexed  # federation-edge-hardening slice 1: WRITE-TIME instance identity, stamped server-side in
+                               # resources/Memory.ts from resources/instance-identity.ts's localInstanceId() — never client-writable.
+                               # Nullable (existing rows read null = clean upgrade). Distinct from the legacy _originatorInstanceId
+                               # (Federation.ts's mergeRecord — stamped by the RECEIVER at merge time, forgeable/lossy); this field is
+                               # stamped by the ORIGINATING instance itself and preserved (never re-stamped) as the record flows through
+                               # sync merges. @indexed for the later sync push-query filter (per-record signature verification and the
+                               # classifier org-gate are separate, later slices — not built here).
+  entities: [String] @indexed  # attention-plane vocabulary strings (flair#675). Added in v1 (not v2) per K&S
+                               # verdict on FLAIR-ATTENTION-PLANE.md — gives the future attention query
+                               # uniform index pushdown across Memory/WorkspaceState/OrgEvent instead of a
+                               # partial one. Optional/derivable-on-write (no automatic tagging built here —
+                               # that producer is a follow-up); additive/nullable, existing rows carry no
+                               # entities, readers tolerate absent (same pattern as Presence.activityUpdatedAt).
+                               # See docs/entity-vocabulary.md.
 }
 
 # Explicit entity-to-entity relationships with temporal validity.
 # Enables queries like "who was team lead in Q1?" or "what changed about X on date Y?"
 # Inspired by knowledge graph triples with time-bounded validity windows.
+#
+# attention-plane vocabulary note (flair#675): Relationship gets NO `entities`
+# field. `subject`/`object` already hold free-form entity-reference strings
+# and are already @indexed — they're the vocabulary carrier for this table.
+# (Today they're lowercased on write in resources/Relationship.ts's put() but
+# not yet validated against resources/entity-vocab.ts — wiring that
+# validation, so `subject`/`object` are enforced attention-plane vocabulary
+# strings, is a follow-up, not this foundation slice.)
 type Relationship @table(database: "flair") {
   id: ID @primaryKey
   agentId: String! @indexed        # who created this relationship
@@ -48,6 +95,16 @@ type Relationship @table(database: "flair") {
   source: String                   # where this was learned (memory ID, conversation, etc.)
   createdAt: String! @indexed
   updatedAt: String
+  originatorInstanceId: String @indexed  # federation-edge-hardening slice 1 — see Memory.originatorInstanceId's doc above
+                                    # for the full contract (write-time stamp, nullable, preserved across sync merges).
+                                    # Stamped server-side in resources/Relationship.ts's put().
+  provenance: String                # JSON blob (relationship-write-path, folded K&S refinement): SAME shape as
+                                    # Memory.provenance above — { v, verified: { agentId, timestamp }, claimed?: { model } }
+                                    # — via the shared resources/provenance.ts buildProvenance(), never a
+                                    # Relationship-specific format. Nullable by design — pre-existing rows read back
+                                    # provenance = null, unchanged behavior (migration-equivalence gate, same
+                                    # discipline as Memory.usageCount/flair#684). Stamped server-side in
+                                    # resources/Relationship.ts's put(); never client-writable.
 }
 
 type Soul @table(database: "flair") {
@@ -60,6 +117,9 @@ type Soul @table(database: "flair") {
   durability: String @indexed
   createdAt: String!
   updatedAt: String
+  originatorInstanceId: String @indexed  # federation-edge-hardening slice 1 — see Memory.originatorInstanceId's doc above
+                                    # for the full contract (write-time stamp, nullable, preserved across sync merges).
+                                    # Stamped server-side in resources/Soul.ts's post()/put().
 }
 
 type MemoryGrant @table(database: "flair") @export {
@@ -71,6 +131,28 @@ type MemoryGrant @table(database: "flair") @export {
   createdAt: String
 }
 
+# MemoryUsage — the dedup ledger for the usage-feedback signal (flair#683).
+# One row per (agentId, memoryId) contribution: `id` is the deterministic
+# composite key `${agentId}:${memoryId}`, so "has this agent already
+# contributed to this memory's usageCount" is a single point-lookup, not a
+# query. This is what makes the anti-gaming dedup rule ("each (agent, memory)
+# pair contributes at most 1 to usageCount" — Sherlock) enforceable: the
+# dedicated endpoint (resources/MemoryUsage.ts) only bumps Memory.usageCount
+# when a NEW row is created here; a repeat call from the same agent for the
+# same memory is a no-op against a row that already exists.
+#
+# `attribution` is OPAQUE — never parsed, never fed to an LLM, never rendered
+# — a free-text "what used this" hint the caller supplies, sanitized
+# (control-character-stripped, length-capped) and stored as-is for
+# analytics/audit only. Never trust it as anything more than a label.
+type MemoryUsage @table(database: "flair") {
+  id: ID @primaryKey           # `${agentId}:${memoryId}` — the dedup key itself
+  agentId: String! @indexed    # the contributing (verified) agent — never client-forgeable
+  memoryId: String! @indexed   # the memory this contribution counted toward
+  attribution: String          # opaque/sanitized free-text hint (optional)
+  createdAt: String!
+}
+
 # MemoryCandidate — staged distillations from the FLAIR-NIGHTLY-REM cycle.
 # Per specs/FLAIR-NIGHTLY-REM.md § 7. Slice 1 of ops-2qq adds the schema +
 # `flair rem candidates` listing command. Future slices wire the nightly

package/schemas/schema.graphql

@@ -3,48 +3,10 @@
 
 type Presence @table(database: "flair") @export {
   agentId: ID @primaryKey
-  lastHeartbeatAt: BigInt        # unix ms timestamp
+  lastHeartbeatAt: BigInt        # unix ms timestamp — pure liveness beacon; every heartbeat refreshes it
   currentTask: String            # short human string, e.g. "Reviewing flair#467"
-  activity: String @indexed      # "coding" | "reviewing" | "planning" | "idle"
-}
-
-# ─── Observatory tables ───────────────────────────────────────────────────────
-
-type ObsOffice @table(database: "flair") @export {
-  id: ID @primaryKey        # e.g. "office1"
-  name: String!
-  publicKey: String!        # Ed25519 hex public key for auth verification
-  status: String @indexed   # "online" | "offline" | "degraded"
-  lastSeen: String
-  agentCount: Int
-  createdAt: String!
-  updatedAt: String
-}
-
-type ObsAgentSnapshot @table(database: "flair") @export {
-  id: ID @primaryKey        # "{officeId}:{agentId}"
-  officeId: String! @indexed
-  agentId: String! @indexed
-  name: String
-  role: String
-  type: String              # "agent" | "human"
-  model: String
-  status: String @indexed   # "active" | "idle" | "offline"
-  currentTask: String
-  lastActivity: String
-  lastHeartbeat: String
-  updatedAt: String!
-}
-
-type ObsEventFeed @table(database: "flair") @export {
-  id: ID @primaryKey        # "{officeId}:{eventId}"
-  officeId: String! @indexed
-  kind: String! @indexed
-  authorId: String! @indexed
-  summary: String!
-  refId: String @indexed
-  scope: String @indexed
-  createdAt: String! @indexed
-  receivedAt: String!
-  expiresAt: String @indexed
+  activity: String @indexed      # "coding" | "reviewing" | "planning" | "debugging" | "idle"
+  activityUpdatedAt: BigInt      # unix ms — when activity/currentTask were last ASSERTED (natural-presence); nullable/additive, absent on records written before this feature (readers fall back to lastHeartbeatAt)
+  flairVersion: String           # @tpsdev-ai/flair version serving this heartbeat (flair#639); absent on pre-#639 records
+  harperVersion: String          # @harperfast/harper version serving this heartbeat (flair#639); absent on pre-#639 records
 }

package/schemas/workspace.graphql

@@ -11,4 +11,7 @@ type WorkspaceState @table(database: "flair") @export {
   summary: String
   filesChanged: [String]
   createdAt: String!
+  entities: [String] @indexed  # attention-plane vocabulary strings (flair#675); additive/nullable —
+                               # existing rows carry no entities, readers tolerate absent (same
+                               # pattern as Presence.activityUpdatedAt). See docs/entity-vocabulary.md.
 }

package/dist/resources/IngestEvents.js

@@ -1,162 +0,0 @@
-/**
- * IngestEvents.ts — Observatory ingestion endpoint.
- *
- * POST /IngestEvents
- * Auth: TPS-Ed25519 signed by the office's private key (verified against
- *       ObsOffice.publicKey stored at registration time).
- *
- * Body: {
- *   officeId: string;
- *   events:   OrgEventRecord[];
- *   agents:   AgentStatus[];
- *   syncedAt: string;
- * }
- *
- * Actions:
- *   1. Verify Ed25519 signature against stored office public key
- *   2. Upsert ObsAgentSnapshot for each agent
- *   3. Insert ObsEventFeed for each new event (30-day TTL)
- *   4. Update ObsOffice.lastSeen + agentCount
- *
- * Rate limit: 1 call / 10s per office (enforced by createdAt delta check)
- * Batch limit: 100 events per call
- */
-import { Resource, databases } from "@harperfast/harper";
-import { createPublicKey, verify } from "node:crypto";
-const BATCH_LIMIT = 100;
-const RATE_LIMIT_MS = 10_000;
-const EVENT_TTL_DAYS = 30;
-function verifyEd25519Signature(publicKeyHex, authHeader, officeId) {
-    try {
-        // Header format: TPS-Ed25519 officeId:ts:nonce:sig
-        const prefix = "TPS-Ed25519 ";
-        if (!authHeader.startsWith(prefix))
-            return false;
-        const parts = authHeader.slice(prefix.length).split(":");
-        if (parts.length < 4)
-            return false;
-        const [id, ts, nonce, ...sigParts] = parts;
-        const sig = sigParts.join(":");
-        if (id !== officeId)
-            return false;
-        // Replay protection: reject signatures older than 5 minutes
-        const age = Date.now() - Number(ts);
-        if (age > 5 * 60 * 1000 || age < -30_000)
-            return false;
-        const pubKeyBytes = Buffer.from(publicKeyHex.replace(/=\s*/g, ""), "hex");
-        const spkiHeader = Buffer.from("302a300506032b6570032100", "hex");
-        const pubKey = createPublicKey({ key: Buffer.concat([spkiHeader, pubKeyBytes]), format: "der", type: "spki" });
-        const payload = Buffer.from(`${id}:${ts}:${nonce}:POST:/IngestEvents`);
-        const sigBuf = Buffer.from(sig, "base64");
-        return verify(null, payload, pubKey, sigBuf);
-    }
-    catch {
-        return false;
-    }
-}
-export class IngestEvents extends Resource {
-    // Public POST by design: the handler self-verifies the OFFICE's Ed25519
-    // signature against ObsOffice.publicKey (not an agent identity), so it can't use
-    // agent auth. allowCreate=true lets the request reach post() where that
-    // verification happens — same self-gating pattern as FederationPair/FederationSync.
-    allowCreate() {
-        return true;
-    }
-    async post(body, context) {
-        // Harper v5 does not populate this.request on Resource subclasses —
-        // getContext() is the only reliable path (ops-sal4: the previous
-        // `(this as any).request` read was always undefined, so authHeader was
-        // always undefined and every request 401'd before reaching the office
-        // Ed25519 signature check below).
-        const ctx = this.getContext?.();
-        const request = ctx?.request ?? ctx;
-        const authHeader = request?.headers?.get?.("authorization") ?? request?.headers?.authorization;
-        // Parse and validate body
-        let payload;
-        try {
-            payload = (typeof body === "string" ? JSON.parse(body) : body);
-        }
-        catch {
-            return new Response(JSON.stringify({ error: "invalid JSON" }), { status: 400, headers: { "Content-Type": "application/json" } });
-        }
-        const { officeId, events = [], agents = [], syncedAt } = payload;
-        if (!officeId) {
-            return new Response(JSON.stringify({ error: "officeId required" }), { status: 400, headers: { "Content-Type": "application/json" } });
-        }
-        // Look up the office
-        const office = await databases.flair.ObsOffice.get(officeId).catch(() => null);
-        if (!office) {
-            return new Response(JSON.stringify({ error: "office not registered — POST /ObsOffice first" }), { status: 403, headers: { "Content-Type": "application/json" } });
-        }
-        // Verify Ed25519 signature
-        if (!authHeader || !verifyEd25519Signature(String(office.publicKey), authHeader, officeId)) {
-            return new Response(JSON.stringify({ error: "invalid signature" }), { status: 401, headers: { "Content-Type": "application/json" } });
-        }
-        // Rate limit check
-        if (office.lastSeen) {
-            const msSinceLastSync = Date.now() - new Date(office.lastSeen).getTime();
-            if (msSinceLastSync < RATE_LIMIT_MS) {
-                return new Response(JSON.stringify({ error: "rate limit: 1 call per 10s" }), { status: 429, headers: { "Content-Type": "application/json" } });
-            }
-        }
-        // Batch limit
-        if (events.length > BATCH_LIMIT) {
-            return new Response(JSON.stringify({ error: `batch limit: max ${BATCH_LIMIT} events` }), { status: 400, headers: { "Content-Type": "application/json" } });
-        }
-        const now = new Date().toISOString();
-        const expiresAt = new Date(Date.now() + EVENT_TTL_DAYS * 24 * 60 * 60 * 1000).toISOString();
-        // Upsert agent snapshots
-        for (const agent of agents) {
-            if (!agent.agentId)
-                continue;
-            const snapshotId = `${officeId}:${agent.agentId}`;
-            await databases.flair.ObsAgentSnapshot.put({
-                id: snapshotId,
-                officeId,
-                agentId: agent.agentId,
-                name: agent.name ?? agent.agentId,
-                role: agent.role,
-                status: agent.status ?? "unknown",
-                model: agent.model,
-                lastActivity: agent.lastSeen ?? now,
-                lastHeartbeat: now,
-                updatedAt: now,
-            }).catch((e) => console.warn(`[IngestEvents] snapshot upsert failed for ${snapshotId}: ${e.message}`));
-        }
-        // Insert event feed entries (skip duplicates)
-        let inserted = 0;
-        for (const ev of events) {
-            if (!ev.id || !ev.kind)
-                continue;
-            const feedId = `${officeId}:${ev.id}`;
-            const existing = await databases.flair.ObsEventFeed.get(feedId).catch(() => null);
-            if (existing)
-                continue;
-            await databases.flair.ObsEventFeed.put({
-                id: feedId,
-                officeId,
-                kind: ev.kind,
-                authorId: ev.authorId,
-                summary: ev.summary,
-                refId: ev.refId,
-                scope: ev.scope,
-                createdAt: ev.createdAt,
-                receivedAt: now,
-                expiresAt,
-            }).catch((e) => console.warn(`[IngestEvents] event insert failed for ${feedId}: ${e.message}`));
-            inserted++;
-        }
-        // Update office lastSeen + agentCount
-        await databases.flair.ObsOffice.put({
-            ...office,
-            status: "online",
-            lastSeen: now,
-            agentCount: agents.length,
-            updatedAt: now,
-        }).catch(() => { });
-        return new Response(JSON.stringify({ ok: true, events: inserted, agents: agents.length }), {
-            status: 200,
-            headers: { "Content-Type": "application/json" },
-        });
-    }
-}

package/dist/resources/IssueTokens.js

@@ -1,19 +0,0 @@
-import { Resource, databases } from "@harperfast/harper";
-export class IssueTokens extends Resource {
-    static loadAsInstance = false;
-    async get(_target) {
-        const { refresh_token: refreshToken, operation_token: jwt } = await databases.system.hdb_user.operation({ operation: "create_authentication_tokens" }, this.getContext());
-        return { refreshToken, jwt };
-    }
-    async post(_target, data) {
-        if (!data?.username || !data?.password) {
-            throw new Error("username and password are required");
-        }
-        const { refresh_token: refreshToken, operation_token: jwt } = await databases.system.hdb_user.operation({
-            operation: "create_authentication_tokens",
-            username: data.username,
-            password: data.password,
-        });
-        return { refreshToken, jwt };
-    }
-}

package/dist/resources/ObsAgentSnapshot.js

@@ -1,13 +0,0 @@
-import { databases } from "@harperfast/harper";
-import { allowVerified, allowAdmin } from "./agent-auth.js";
-/**
- * ObsAgentSnapshot — observatory per-agent snapshot read-model. Writes are
- * system-driven (internal sync); agents may read. See ObsOffice for the
- * allowRead=allowVerified security default (flag for Sherlock).
- */
-export class ObsAgentSnapshot extends databases.flair.ObsAgentSnapshot {
-    allowRead() { return allowVerified(this.getContext?.()); }
-    allowCreate() { return allowAdmin(this.getContext?.()); }
-    allowUpdate() { return allowAdmin(this.getContext?.()); }
-    allowDelete() { return allowAdmin(this.getContext?.()); }
-}

package/dist/resources/ObsEventFeed.js

@@ -1,13 +0,0 @@
-import { databases } from "@harperfast/harper";
-import { allowVerified, allowAdmin } from "./agent-auth.js";
-/**
- * ObsEventFeed — observatory event-feed read-model. Writes are system-driven
- * (internal sync); agents may read. See ObsOffice for the allowRead=allowVerified
- * security default (flag for Sherlock).
- */
-export class ObsEventFeed extends databases.flair.ObsEventFeed {
-    allowRead() { return allowVerified(this.getContext?.()); }
-    allowCreate() { return allowAdmin(this.getContext?.()); }
-    allowUpdate() { return allowAdmin(this.getContext?.()); }
-    allowDelete() { return allowAdmin(this.getContext?.()); }
-}

package/dist/resources/ObsOffice.js

@@ -1,19 +0,0 @@
-import { databases } from "@harperfast/harper";
-import { allowVerified, allowAdmin } from "./agent-auth.js";
-/**
- * ObsOffice — observatory office-layout read-model. Writes are system-driven
- * (internal sync); agents may read. Self-authorizes now that the global gate is
- * non-rejecting.
- *
- * SECURITY DEFAULT (flag for Sherlock): allowRead is allowVerified (anonymous
- * denied). The ObservationCenter HTML shell is public but its data API calls
- * authenticate (admin-pass). If the public Office Space renderer needs anonymous
- * Obs reads, relax to allowRead=true WITH field-allowlisting (as Presence.get does)
- * — do NOT expose raw rows publicly.
- */
-export class ObsOffice extends databases.flair.ObsOffice {
-    allowRead() { return allowVerified(this.getContext?.()); }
-    allowCreate() { return allowAdmin(this.getContext?.()); }
-    allowUpdate() { return allowAdmin(this.getContext?.()); }
-    allowDelete() { return allowAdmin(this.getContext?.()); }
-}

package/dist/resources/ObservationCenter.js

@@ -1,23 +0,0 @@
-import { Resource } from "@harperfast/harper";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
-const HERE = dirname(fileURLToPath(import.meta.url));
-const HTML_PATH = resolve(HERE, "..", "..", "ui", "observation-center.html");
-const HTML = readFileSync(HTML_PATH, "utf8");
-/**
- * GET /ObservationCenter — serves the read-only dashboard shell.
- * The HTML handles its own Basic-auth prompt and polls authenticated JSON endpoints.
- */
-export class ObservationCenter extends Resource {
-    // The dashboard shell is just HTML + inline JS; the JS prompts the user
-    // for admin-pass and authenticates each API call. The shell itself is
-    // intentionally public so it can render before auth happens.
-    allowRead() { return true; }
-    async get() {
-        return new Response(HTML, {
-            status: 200,
-            headers: { "content-type": "text/html; charset=utf-8" },
-        });
-    }
-}