From 9f3258c04b0485583e4934e63e438c3915d7f061 Mon Sep 17 00:00:00 2001 From: GLDRoger <130458023+GLDRoger@users.noreply.github.com> Date: Sun, 8 Nov 2026 18:06:44 +0530 Subject: [PATCH 1/4] feat(kin): arm deferrals from memory and confirm them (TRIG-7) The front-matter cache now hands each new snapshot to KinTriggerService.syncOrg, which upserts or disarms a deferral's once triggers and records its recheck snapshot in kin_deferral_runs (provisional K017). Default-branch commits move the cache forward, so a kin_defer item arms as soon as its wake-up commits. A KinDeferralCard is posted to the item's chat and kept in step with re-arms and disarms. Card taps reuse the owner-check tap verification and stay gated until the owner-tap dispatcher lands; the spec lists the remaining steps. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/chat/KinChatService.ts | 9 + apps/server/src/kin/lead/layer.ts | 7 + apps/server/src/kin/memory/Memory.ts | 54 +++- .../src/kin/memory/MemoryWriter.test.ts | 63 +++- apps/server/src/kin/memory/MemoryWriter.ts | 18 ++ .../src/kin/persistence/KinMigrations.test.ts | 7 + .../src/kin/persistence/KinMigrations.ts | 3 + .../migrations/K017_DeferralRuns.ts | 17 + .../kin/triggers/KinTriggerService.test.ts | 227 +++++++++++++ .../src/kin/triggers/KinTriggerService.ts | 301 ++++++++++++++++++ .../server/src/kin/triggers/deferrals.test.ts | 128 ++++++++ apps/server/src/kin/triggers/deferrals.ts | 164 ++++++++++ apps/server/src/kin/triggers/ownerCheck.ts | 139 ++++---- apps/server/src/kin/widgets/deferralCard.ts | 4 + apps/server/src/kin/widgets/registry.ts | 8 +- docs/kin/specs/triggers.md | 15 +- packages/contracts/src/kinLead.ts | 11 +- 17 files changed, 1104 insertions(+), 71 deletions(-) create mode 100644 apps/server/src/kin/persistence/migrations/K017_DeferralRuns.ts create mode 100644 apps/server/src/kin/triggers/KinTriggerService.test.ts create mode 100644 apps/server/src/kin/triggers/KinTriggerService.ts create mode 100644 apps/server/src/kin/triggers/deferrals.test.ts create mode 100644 apps/server/src/kin/triggers/deferrals.ts create mode 100644 apps/server/src/kin/widgets/deferralCard.ts diff --git a/apps/server/src/kin/chat/KinChatService.ts b/apps/server/src/kin/chat/KinChatService.ts index 9ddf482ff10a..dc8b9119486e 100644 --- a/apps/server/src/kin/chat/KinChatService.ts +++ b/apps/server/src/kin/chat/KinChatService.ts @@ -49,6 +49,7 @@ import * as SqlError from "effect/sql/SqlError"; import * as SecureRandom from "effect/crypto/SecureRandom"; import { toPersistenceSqlError } from "../../persistence/Errors.ts"; import { validateState } from "../widgets/registry.ts"; +import { deferralCardActions, deferralCardActionsReady } from "../widgets/deferralCard.ts"; import * as Hub from "./KinChatHub.ts"; import * as Repository from "./KinChatRepository.ts"; import type { AgentIdentity, PersonIdentity } from "./KinIdentity.ts"; @@ -1088,6 +1089,14 @@ const make = Effect.gen(function* () { ) return yield* invalidState; } + if (widget.type === "deferral") { + if (member.role !== "owner") return yield* notAllowed; + if ( + !deferralCardActionsReady || + !deferralCardActions.some((action) => action === request.actionId) + ) + return yield* notAllowed; + } const body = yield* encodeAction({ widgetId: request.widgetId, revision: request.revision, diff --git a/apps/server/src/kin/lead/layer.ts b/apps/server/src/kin/lead/layer.ts index 208f96ba6f7f..685c2742aa7d 100644 --- a/apps/server/src/kin/lead/layer.ts +++ b/apps/server/src/kin/lead/layer.ts @@ -4,6 +4,7 @@ import * as OwnerCheck from "../triggers/ownerCheck.ts"; import * as TriggerScheduler from "../triggers/KinTriggerScheduler.ts"; import * as TriggerStore from "../triggers/KinTriggerStore.ts"; import * as TriggerInbox from "../triggers/KinTriggerInbox.ts"; +import * as TriggerService from "../triggers/KinTriggerService.ts"; import { forkParked } from "../../serverActivation.ts"; import { KinOrgId, KinChatId, KinMessageId } from "@t3tools/contracts"; import * as SecureRandom from "effect/crypto/SecureRandom"; @@ -126,6 +127,12 @@ const withServices = (entry: Layer.Layer) => }), ).pipe(Layer.provide(KinChatRepository.layer)), ), + Layer.provide( + TriggerService.syncHooksLayer.pipe( + Layer.provide(TriggerService.layer), + Layer.provide(KinChatRepository.layer), + ), + ), Layer.provide(KinPersistence.layer), ); diff --git a/apps/server/src/kin/memory/Memory.ts b/apps/server/src/kin/memory/Memory.ts index d8aafb19a722..f788121b6fde 100644 --- a/apps/server/src/kin/memory/Memory.ts +++ b/apps/server/src/kin/memory/Memory.ts @@ -21,6 +21,7 @@ import * as DateTime from "effect/DateTime"; import * as Effect from "effect/Effect"; import * as FileSystem from "effect/FileSystem"; import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; import * as Path from "effect/Path"; import * as Schema from "effect/Schema"; import * as Semaphore from "effect/Semaphore"; @@ -129,6 +130,22 @@ export class MemoryRecoveryHooks extends Context.Service< } >()("t3/kin/memory/Memory/MemoryRecoveryHooks") {} +export class MemorySyncHookError extends Schema.TaggedError()( + "MemorySyncHookError", + { orgId: Schema.String, cause: Schema.Defect() }, +) {} + +/** Receives every newly loaded snapshot; must be idempotent, since a failure retries on the next load. */ +export class MemorySyncHooks extends Context.Service< + MemorySyncHooks, + { + readonly syncItems: ( + orgId: KinOrgId, + items: ReadonlyArray, + ) => Effect.Effect; + } +>()("t3/kin/memory/Memory/MemorySyncHooks") {} + export class Memory extends Context.Service< Memory, { @@ -218,6 +235,9 @@ const make = Effect.gen(function* () { const path = yield* Path.Path; const sql = yield* SqlClient.SqlClient; const writerLocks = new Map(); + const pinnedHeads = new Map(); + const syncedHeads = new Map(); + const syncHooks = yield* Effect.serviceOption(MemorySyncHooks); const withWriterLock = (orgId: KinOrgId, effect: Effect.Effect) => { let lock = writerLocks.get(orgId); if (!lock) { @@ -281,6 +301,9 @@ const make = Effect.gen(function* () { operation: "record", reason: "Anchor changed", }); + // The front-matter cache follows commits to the default branch. + if (branch === (config.defaultBranch ?? "main") && pinnedHeads.get(orgId) === previous) + pinnedHeads.set(orgId, head); }), ) .pipe( @@ -297,7 +320,6 @@ const make = Effect.gen(function* () { }); const cache = yield* MemoryCache.MemoryCache; const locks = new Map(); - const pinnedHeads = new Map(); const initializedCheckouts = new Set(); const duplicateWarnings = new Map>(); const snapshots = new Map(); @@ -530,7 +552,10 @@ const make = Effect.gen(function* () { return { writer: paths.writer, read: paths.read }; }); - const load = Effect.fn("Memory.load")(function* (orgId: KinOrgId, force = false) { + const loadSnapshot = Effect.fn("Memory.loadSnapshot")(function* ( + orgId: KinOrgId, + force: boolean, + ) { const paths = yield* pathsFor(orgId); const pinned = pinnedHeads.get(orgId); if (pinned === undefined) yield* validateWriter(orgId, paths, false); @@ -702,6 +727,31 @@ const make = Effect.gen(function* () { } return snapshot; }); + const load = Effect.fn("Memory.load")(function* (orgId: KinOrgId, force = false) { + const snapshot = yield* loadSnapshot(orgId, force); + if (Option.isSome(syncHooks) && syncedHeads.get(orgId) !== snapshot.head) { + const counts = new Map(); + for (const { head } of snapshot.items) counts.set(head.id, (counts.get(head.id) ?? 0) + 1); + yield* syncHooks.value + .syncItems( + orgId, + snapshot.items.map(({ head }) => ({ + ...head, + duplicate: (counts.get(head.id) ?? 0) > 1, + })), + ) + .pipe( + Effect.tap(() => Effect.sync(() => syncedHeads.set(orgId, snapshot.head))), + Effect.catch((error) => + Effect.logWarning("Could not sync memory triggers; retrying on next load", { + orgId, + errorTag: error._tag, + }), + ), + ); + } + return snapshot; + }); const query = Effect.fn("Memory.query")(function* (orgId: KinOrgId, q: MemoryQuery) { for (const value of [q.dueBefore, q.dueAfter]) { diff --git a/apps/server/src/kin/memory/MemoryWriter.test.ts b/apps/server/src/kin/memory/MemoryWriter.test.ts index e30d07c19942..955ed554ac08 100644 --- a/apps/server/src/kin/memory/MemoryWriter.test.ts +++ b/apps/server/src/kin/memory/MemoryWriter.test.ts @@ -3,7 +3,12 @@ import { memoryGit } from "./git.ts"; import * as NodeZlib from "node:zlib"; import * as NodeServices from "@effect/platform-node/NodeServices"; import { expect, it } from "@effect/vitest"; -import { KinAgentId, KinOrgId, VcsProcessSpawnError } from "@t3tools/contracts"; +import { + KinAgentId, + KinOrgId, + type MemoryItemHead, + VcsProcessSpawnError, +} from "@t3tools/contracts"; import * as Effect from "effect/Effect"; import * as FileSystem from "effect/FileSystem"; import * as Layer from "effect/Layer"; @@ -58,6 +63,7 @@ it.live.each([ "review-null", "credentials", "read-during-record", + "deferral-card-remind", "H3-packed-ref", "M1-unanchored", "M2-nondescendant", @@ -120,6 +126,10 @@ it.live.each([ }), ); } + if (scenario === "deferral-card-remind") { + yield* fs.makeDirectory(`${source}/deferrals`); + yield* fs.writeFileString(`${source}/deferrals/def-001.md`, fixtureItem()); + } if (scenario === "B5-journal" || scenario === "P4-journal") { yield* fs.makeDirectory(`${source}/journal/2026`, { recursive: true }); yield* fs.writeFile( @@ -207,9 +217,18 @@ it.live.each([ credentialHelper: "fixture-server-helper", repositories: [{ orgId, repoUrl: remote, path: "state" }], }); + const synced: Array> = []; const memoryLayer = Memory.layer.pipe( Layer.provide(config), Layer.provide(Layer.succeed(Memory.MemoryRecoveryHooks, { notify: () => Effect.void })), + Layer.provide( + Layer.succeed(Memory.MemorySyncHooks, { + syncItems: (_org, items) => + Effect.sync(() => { + synced.push(items); + }), + }), + ), ); const hooks = Layer.succeed(Writer.MemoryWriterHooks, { notify: Effect.fn("Test.notice")((notice) => @@ -233,7 +252,8 @@ it.live.each([ level: scenario === "conflict" || scenario === "B5-journal" || - scenario === "read-during-record" + scenario === "read-during-record" || + scenario === "deferral-card-remind" ? "L1" : "L0", timeZone: "Asia/Kolkata", @@ -258,11 +278,20 @@ it.live.each([ itemId: scenario === "owner-other-item-keep" ? "other-item" : "def-001", action: scenario === "owner-drop-keep" ? "drop" : "keep", } - : { - saidBy: "fixture-owner", - trust: "owner", - source: "fixture-owner-message", - }, + : scenario === "deferral-card-remind" + ? { + saidBy: "fixture-owner", + trust: "owner", + source: "fixture-owner-message", + kind: "deferral_card", + itemId: "def-001", + action: "remind", + } + : { + saidBy: "fixture-owner", + trust: "owner", + source: "fixture-owner-message", + }, ], [ "member", @@ -609,6 +638,26 @@ it.live.each([ ).toBe("Success"); return; } + if (scenario === "deferral-card-remind") { + const stage = (onDue: string) => + writer + .stage(orgId, "wake1", { + path: "deferrals/def-001.md", + content: fixtureItem({ on_due: onDue }), + sourceEventId: "owner", + }) + .pipe(Effect.result); + const forged = yield* stage("ask"); + expect(forged._tag === "Failure" && forged.failure._tag).toBe("MemoryConflict"); + expect((yield* stage("remind"))._tag).toBe("Success"); + const committed = yield* writer.commitWakeup(orgId, "wake1", "completed"); + expect( + yield* git(paths.writer, ["show", `${committed.commit}:deferrals/def-001.md`]), + ).toContain("on_due: remind"); + const last = synced.at(-1)?.find((item) => item.id === "def-001"); + expect(last?.on_due).toBe("remind"); + return; + } if (scenario.endsWith("-keep")) { const content = fixtureItem({ kind: "claim", diff --git a/apps/server/src/kin/memory/MemoryWriter.ts b/apps/server/src/kin/memory/MemoryWriter.ts index 1a00cc70a83f..086f8fb38d09 100644 --- a/apps/server/src/kin/memory/MemoryWriter.ts +++ b/apps/server/src/kin/memory/MemoryWriter.ts @@ -47,6 +47,7 @@ export interface WakeupContext extends JournalContext { readonly itemId: string; readonly action: "keep" | "update" | "drop"; } + | { readonly kind: "deferral_card"; readonly itemId: string; readonly action: "remind" } ) >; } @@ -531,6 +532,13 @@ const make = Effect.gen(function* () { source.action === "keep" ) mutable.add("review_by"); + if ( + source.kind === "deferral_card" && + source.itemId === item.id && + item.kind === "deferral" && + fm.on_due === "remind" + ) + mutable.add("on_due"); if ( Object.entries(item).some( ([key, value]) => @@ -804,6 +812,16 @@ const make = Effect.gen(function* () { recorded, ]); yield* memory.record(orgId, branch, recorded, commit); + // Arms deferrals from the commit now, not at the next wake-up. + if (branch === (config.defaultBranch ?? "main")) + yield* memory.rebuildCache(orgId).pipe( + Effect.catch((error) => + Effect.logWarning("Could not refresh memory cache after commit", { + orgId, + errorTag: error._tag, + }), + ), + ); yield* push(commit); return { commit }; }), diff --git a/apps/server/src/kin/persistence/KinMigrations.test.ts b/apps/server/src/kin/persistence/KinMigrations.test.ts index 98163746ceca..1e301dddb8cf 100644 --- a/apps/server/src/kin/persistence/KinMigrations.test.ts +++ b/apps/server/src/kin/persistence/KinMigrations.test.ts @@ -21,6 +21,7 @@ const tableNames = [ "kin_chat_members", "kin_chats", "kin_cursor", + "kin_deferral_runs", "kin_events", "kin_floor_grants", "kin_floor_notices", @@ -108,6 +109,7 @@ describe("Kin migrations", () => { { migration_id: 13, name: "Routines" }, { migration_id: 14, name: "LeadToolCalls" }, { migration_id: 15, name: "AuthSessionKeys" }, + { migration_id: 17, name: "DeferralRuns" }, ]); assert.deepStrictEqual( upstreamBefore.map((row) => [row.migration_id, row.name] as const), @@ -169,6 +171,7 @@ describe("Kin migrations", () => { { migration_id: 13, name: "Routines" }, { migration_id: 14, name: "LeadToolCalls" }, { migration_id: 15, name: "AuthSessionKeys" }, + { migration_id: 17, name: "DeferralRuns" }, ]); assert.deepStrictEqual(yield* upstreamHistory, upstreamBefore); assert.deepStrictEqual(yield* sql`SELECT * FROM kin_orgs`, [ @@ -255,6 +258,7 @@ describe("Kin migrations", () => { [13, "Routines"], [14, "LeadToolCalls"], [15, "AuthSessionKeys"], + [17, "DeferralRuns"], ]); const before = yield* kinSchema; assert.deepStrictEqual( @@ -283,6 +287,7 @@ describe("Kin migrations", () => { yield* sql`DROP INDEX idx_kin_messages_changes`; yield* sql`ALTER TABLE kin_messages DROP COLUMN change_seq`; yield* sql`ALTER TABLE kin_chats DROP COLUMN change_seq`; + yield* sql`DROP TABLE kin_deferral_runs`; yield* sql`DROP TABLE kin_auth_key_repairs`; yield* sql`DROP TABLE kin_auth_session_keys`; yield* sql`DROP TABLE kin_judge_log`; @@ -317,6 +322,7 @@ describe("Kin migrations", () => { [13, "Routines"], [14, "LeadToolCalls"], [15, "AuthSessionKeys"], + [17, "DeferralRuns"], ]); assert.deepStrictEqual( yield* sql`SELECT member_id FROM kin_chat_members WHERE org_id = 'org' ORDER BY member_id`, @@ -357,6 +363,7 @@ describe("Kin migrations", () => { { migration_id: 13, name: "Routines" }, { migration_id: 14, name: "LeadToolCalls" }, { migration_id: 15, name: "AuthSessionKeys" }, + { migration_id: 17, name: "DeferralRuns" }, ]); assert.deepStrictEqual(yield* runKinMigrations(), []); assert.deepStrictEqual(yield* runMigrations(), []); diff --git a/apps/server/src/kin/persistence/KinMigrations.ts b/apps/server/src/kin/persistence/KinMigrations.ts index 47b195065a1c..daacd35bb652 100644 --- a/apps/server/src/kin/persistence/KinMigrations.ts +++ b/apps/server/src/kin/persistence/KinMigrations.ts @@ -18,6 +18,8 @@ import SecretAllow from "./migrations/K012_SecretAllow.ts"; import Routines from "./migrations/K013_Routines.ts"; import LeadToolCalls from "./migrations/K014_LeadToolCalls.ts"; import AuthSessionKeys from "./migrations/K015_AuthSessionKeys.ts"; +// Provisional number; renumbered at merge. +import DeferralRuns from "./migrations/K017_DeferralRuns.ts"; const run = Migrator.make({}); const loader = Migrator.fromRecord({ @@ -36,6 +38,7 @@ const loader = Migrator.fromRecord({ "13_Routines": Routines, "14_LeadToolCalls": LeadToolCalls, "15_AuthSessionKeys": AuthSessionKeys, + "17_DeferralRuns": DeferralRuns, }); export const runKinMigrations = Effect.fn("KinMigrations.run")(function* () { diff --git a/apps/server/src/kin/persistence/migrations/K017_DeferralRuns.ts b/apps/server/src/kin/persistence/migrations/K017_DeferralRuns.ts new file mode 100644 index 000000000000..f91ae1f6fbea --- /dev/null +++ b/apps/server/src/kin/persistence/migrations/K017_DeferralRuns.ts @@ -0,0 +1,17 @@ +import * as Effect from "effect/Effect"; +import * as SqlClient from "effect/sql/SqlClient"; + +export default Effect.gen(function* () { + const sql = yield* SqlClient.SqlClient; + // TRIG-7 writes armed/disarmed; the due flow (TRIG-8) owns the remaining states. + yield* sql`CREATE TABLE kin_deferral_runs ( + org_id TEXT NOT NULL REFERENCES kin_orgs(org_id), + item_id TEXT NOT NULL, + state TEXT NOT NULL, + due_at INTEGER CHECK (due_at IS NULL OR typeof(due_at) = 'integer'), + on_due TEXT NOT NULL CHECK (on_due IN ('remind', 'start', 'ask', 'chase')), + snapshot_json TEXT NOT NULL, + updated_at INTEGER NOT NULL CHECK (typeof(updated_at) = 'integer'), + PRIMARY KEY (org_id, item_id) + )`; +}); diff --git a/apps/server/src/kin/triggers/KinTriggerService.test.ts b/apps/server/src/kin/triggers/KinTriggerService.test.ts new file mode 100644 index 000000000000..f5e9ce5fb746 --- /dev/null +++ b/apps/server/src/kin/triggers/KinTriggerService.test.ts @@ -0,0 +1,227 @@ +import { assert, it } from "@effect/vitest"; +import { + KinChatId, + KinDeferralCard, + KinMemoryItemId, + KinOrgId, + KinPersonId, + KinWidgetId, + type MemoryItemHead, +} from "@t3tools/contracts"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Schema from "effect/Schema"; +import * as SqlClient from "effect/sql/SqlClient"; +import * as TestClock from "effect/testing/TestClock"; + +import * as Sqlite from "../../persistence/Sqlite.ts"; +import * as Chat from "../chat/KinChatService.ts"; +import * as Hub from "../chat/KinChatHub.ts"; +import * as Repository from "../chat/KinChatRepository.ts"; +import * as JudgeShadow from "../floor/JudgeShadow.ts"; +import * as Persistence from "../persistence/KinPersistence.ts"; +import * as TriggerService from "./KinTriggerService.ts"; +import { item, orgId, otherOrg, seed } from "./routines.testkit.ts"; + +const decodeCard = Schema.decodeSync(Schema.fromJsonString(KinDeferralCard)); +const now = Date.parse("2026-11-09T09:00:00.000Z"); +const due = "2026-11-13T09:00+05:30"; +const dueAt = Date.parse("2026-11-13T03:30:00.000Z"); + +const layer = TriggerService.layer.pipe( + Layer.provideMerge( + Chat.layer.pipe(Layer.provide(JudgeShadow.layerOff), Layer.provideMerge(Hub.layer)), + ), + Layer.provideMerge(Repository.layer), + Layer.provideMerge(Persistence.layer.pipe(Layer.provideMerge(Sqlite.layerMemory))), +); + +const deferral = (overrides: Partial = {}) => + item("def-1", { + kind: "deferral", + path: "deferrals/def-1.md", + due, + on_due: "start", + chat: KinChatId.make(`chat-${overrides.orgId ?? orgId}`), + ...overrides, + }); + +const setup = Effect.fn("test.deferralSetup")(function* () { + yield* seed(); + const sql = yield* SqlClient.SqlClient; + yield* sql`INSERT INTO kin_trigger_settings VALUES (${orgId}, 'Asia/Kolkata', '08:30', '18:30', '03:00', 0, 1, '09:00', '{"from":"21:00","to":"08:00"}')`; + yield* TestClock.setTime(now); + return { sql, service: yield* TriggerService.KinTriggerService }; +}); + +const triggers = Effect.fn("test.deferralTriggers")(function* (org: string) { + const sql = yield* SqlClient.SqlClient; + return yield* sql<{ + id: string; + enabled: number; + nextRunAt: number | null; + updatedAt: number; + }>`SELECT trigger_id AS id, enabled, next_run_at AS "nextRunAt", updated_at AS "updatedAt" + FROM kin_triggers WHERE org_id = ${org} ORDER BY trigger_id`; +}); + +const card = Effect.fn("test.deferralCard")(function* (org: string) { + const sql = yield* SqlClient.SqlClient; + const rows = yield* sql<{ + revision: number; + state: string; + closedAt: string | null; + }>`SELECT revision, state_json AS state, closed_at AS "closedAt" FROM kin_widgets + WHERE org_id = ${org} AND type = 'deferral' ORDER BY widget_id`; + return rows.map((row) => ({ ...row, state: decodeCard(row.state) })); +}); + +it.effect("arms from front matter, re-arms on edits, and re-syncs without writes", () => + Effect.gen(function* () { + const { sql, service } = yield* setup(); + assert.equal(yield* service.syncItem(deferral()), "armed"); + const armed = yield* triggers(orgId); + assert.deepEqual( + armed.map(({ id, enabled, nextRunAt }) => [id, enabled, nextRunAt]), + [ + ["deferral:def-1:due", 1, dueAt], + ["deferral:def-1:heads_up", 1, dueAt - 30 * 60_000], + ], + ); + const [posted] = yield* card(orgId); + assert.equal(posted?.state.text, "Deferred to Fri 13 Nov, 9:00. I'll start then."); + const [message] = yield* sql<{ body: string }>`SELECT body FROM kin_messages + WHERE org_id = ${orgId} AND kind = 'system' ORDER BY message_id`; + assert.equal(message?.body, posted?.state.text); + + yield* TestClock.adjust("1 minute"); + assert.equal(yield* service.syncItem(deferral()), "unchanged"); + yield* sql`UPDATE kin_triggers SET next_run_at = NULL WHERE org_id = ${orgId} AND trigger_id = 'deferral:def-1:due'`; + assert.equal(yield* service.syncItem(deferral()), "unchanged"); + assert.deepEqual( + (yield* triggers(orgId)).map(({ nextRunAt, updatedAt }) => [nextRunAt, updatedAt]), + [ + [null, now], + [dueAt - 30 * 60_000, now], + ], + ); + assert.equal((yield* card(orgId))[0]?.revision, 1); + + const moved = "2026-11-16T09:00+05:30"; + assert.equal(yield* service.syncItem(deferral({ due: moved })), "armed"); + assert.deepEqual( + (yield* triggers(orgId)).map(({ nextRunAt }) => nextRunAt), + [Date.parse(moved), Date.parse(moved) - 30 * 60_000], + ); + assert.equal(yield* service.syncItem(deferral({ due: moved, on_due: "remind" })), "armed"); + assert.deepEqual( + (yield* triggers(orgId)).map(({ enabled, nextRunAt }) => [enabled, nextRunAt]), + [ + [1, Date.parse(moved)], + [0, null], + ], + ); + const [updated] = yield* card(orgId); + assert.equal(updated?.revision, 3); + assert.equal(updated?.state.text, "Deferred to Mon 16 Nov, 9:00. I'll remind you then."); + const [run] = yield* sql<{ state: string; dueAt: number; onDue: string }>` + SELECT state, due_at AS "dueAt", on_due AS "onDue" FROM kin_deferral_runs + WHERE org_id = ${orgId} ORDER BY item_id`; + assert.deepEqual(run, { state: "armed", dueAt: Date.parse(moved), onDue: "remind" }); + }).pipe(Effect.provide(layer)), +); + +it.effect.each([ + ["done", { status: "done" }], + ["cancelled", { status: "cancelled" }], + ["invalid_at", { invalid_at: "2026-11-09T09:00:00.000Z" }], + ["missing", undefined], +] as const)("disarms on %s and re-arms when reopened", ([, overrides]) => + Effect.gen(function* () { + const { sql, service } = yield* setup(); + yield* service.syncItem(deferral()); + if (overrides === undefined) yield* service.syncOrg(orgId, []); + else assert.equal(yield* service.syncItem(deferral(overrides)), "disarmed"); + assert.deepEqual( + (yield* triggers(orgId)).map(({ enabled, nextRunAt }) => [enabled, nextRunAt]), + [ + [0, null], + [0, null], + ], + ); + assert.isNotNull((yield* card(orgId))[0]?.closedAt); + const [run] = yield* sql<{ state: string }>`SELECT state FROM kin_deferral_runs + WHERE org_id = ${orgId} ORDER BY item_id`; + assert.equal(run?.state, "disarmed"); + assert.equal( + yield* service.syncItem( + overrides === undefined ? deferral({ status: "done" }) : deferral(overrides), + ), + "unchanged", + ); + + yield* service.syncOrg(orgId, [deferral()]); + assert.deepEqual( + (yield* triggers(orgId)).map(({ enabled }) => enabled), + [1, 1], + ); + const [reopened] = yield* card(orgId); + assert.isNull(reopened?.closedAt); + assert.lengthOf(yield* card(orgId), 1); + }).pipe(Effect.provide(layer)), +); + +it.effect("keeps organizations apart", () => + Effect.gen(function* () { + const { sql, service } = yield* setup(); + yield* service.syncItem(deferral()); + yield* service.syncItem(deferral({ orgId: otherOrg })); + yield* service.syncOrg(orgId, [deferral({ orgId: otherOrg, status: "done" })]); + assert.deepEqual( + (yield* triggers(orgId)).map(({ enabled }) => enabled), + [0, 0], + ); + assert.deepEqual( + (yield* triggers(otherOrg)).map(({ enabled }) => enabled), + [1, 1], + ); + assert.equal((yield* card(otherOrg))[0]?.closedAt, null); + + const foreign = item("def-foreign", { + kind: "deferral", + path: "deferrals/def-foreign.md", + due, + chat: KinChatId.make(`chat-${otherOrg}`), + }); + assert.equal(yield* service.syncItem(foreign), "armed"); + assert.lengthOf( + yield* sql`SELECT widget_id FROM kin_widgets WHERE org_id = ${orgId} AND state_json LIKE '%def-foreign%' ORDER BY widget_id`, + 0, + ); + const unknown = yield* service + .syncItem(deferral({ orgId: KinOrgId.make("z") })) + .pipe(Effect.flip); + assert.equal(unknown._tag, "KinTriggerSyncError"); + }).pipe(Effect.provide(layer)), +); + +it.effect("refuses deferral card taps until the owner-tap dispatcher lands", () => + Effect.gen(function* () { + const { service } = yield* setup(); + yield* service.syncItem(deferral()); + const chat = yield* Chat.KinChatService; + const failure = yield* chat + .act( + { _tag: "person", orgId, personId: KinPersonId.make(`owner-${orgId}`) }, + { + widgetId: KinWidgetId.make(`deferral:${orgId}:def-1`), + revision: 1, + actionId: "remind", + value: KinMemoryItemId.make("def-1"), + clientActionId: "remind", + }, + ) + .pipe(Effect.flip); + assert.equal(failure._tag === "KinChatError" && failure.reason, "not_allowed"); + }).pipe(Effect.provide(layer)), +); diff --git a/apps/server/src/kin/triggers/KinTriggerService.ts b/apps/server/src/kin/triggers/KinTriggerService.ts new file mode 100644 index 000000000000..0d817b6bfe1a --- /dev/null +++ b/apps/server/src/kin/triggers/KinTriggerService.ts @@ -0,0 +1,301 @@ +import { + KinChatId, + type KinDeferralCard, + KinMemoryItemId, + KinMessageId, + KinOrgId, + KinTriggerSchedule, + KinTriggerSubject, + KinWidgetId, + type MemoryItemHead, +} from "@t3tools/contracts"; +import * as Clock from "effect/Clock"; +import * as Context from "effect/Context"; +import * as DateTime from "effect/DateTime"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; +import * as Schema from "effect/Schema"; +import * as SqlClient from "effect/sql/SqlClient"; +import { isSqlError } from "effect/sql/SqlError"; + +import { toPersistenceSqlError } from "../../persistence/Errors.ts"; +import { KinChatHub } from "../chat/KinChatHub.ts"; +import * as Repository from "../chat/KinChatRepository.ts"; +import * as Memory from "../memory/Memory.ts"; +import * as MemoryCache from "../memory/MemoryCache.ts"; +import { + confirmText, + DeferralSnapshot, + deferralSnapshot, + deferralTriggerId, + deferralWidgetId, + planDeferral, + type DeferralPhase, + type DeferralPlan, +} from "./deferrals.ts"; + +export class KinTriggerSyncError extends Schema.TaggedError()( + "KinTriggerSyncError", + { orgId: KinOrgId, cause: Schema.Defect() }, +) {} + +type SyncItem = MemoryItemHead & { readonly duplicate?: boolean }; +export type SyncResult = "armed" | "disarmed" | "unchanged"; + +export class KinTriggerService extends Context.Service< + KinTriggerService, + { + /** Upserts or disarms one deferral's triggers from its front matter. Idempotent. */ + readonly syncItem: (item: SyncItem) => Effect.Effect; + /** Syncs a whole snapshot; armed deferrals missing from it are disarmed. */ + readonly syncOrg: ( + orgId: KinOrgId, + items: ReadonlyArray, + ) => Effect.Effect; + } +>()("t3/kin/triggers/KinTriggerService") {} + +const phases: ReadonlyArray = ["heads_up", "due"]; +const disarmedPlan: DeferralPlan = { armed: false, dueAt: null, onDue: "remind", phases: [] }; +const encodeSchedule = Schema.encodeEffect(Schema.fromJsonString(KinTriggerSchedule)); +const decodeSchedule = Schema.decodeUnknownEffect(Schema.fromJsonString(KinTriggerSchedule)); +const encodeSubject = Schema.encodeEffect(Schema.fromJsonString(KinTriggerSubject)); +const encodeSnapshot = Schema.encodeEffect(Schema.fromJsonString(DeferralSnapshot)); +const iso = (ms: number) => DateTime.formatIso(DateTime.makeUnsafe(ms)); + +const make = Effect.gen(function* () { + const sql = yield* SqlClient.SqlClient; + const cache = yield* MemoryCache.MemoryCache; + const repo = yield* Repository.KinChatRepository; + const hub = yield* Effect.serviceOption(KinChatHub); + const publish = (event: Parameters[0]) => + Option.isSome(hub) ? sql.afterCommit(hub.value.publish(event)) : Effect.void; + + const syncTrigger = Effect.fn("KinTriggerService.syncTrigger")(function* ( + orgId: KinOrgId, + itemId: KinMemoryItemId, + phase: DeferralPhase, + runAt: number | undefined, + timeZone: string, + now: number, + ) { + const id = deferralTriggerId(itemId, phase); + const [row] = yield* sql<{ schedule: string; enabled: number; nextRunAt: number | null }>` + SELECT schedule_json AS schedule, enabled, next_run_at AS "nextRunAt" FROM kin_triggers + WHERE org_id = ${orgId} AND trigger_id = ${id} ORDER BY trigger_id + `; + if (runAt === undefined) { + if (row === undefined || (row.enabled === 0 && row.nextRunAt === null)) return false; + yield* sql`UPDATE kin_triggers SET enabled = 0, next_run_at = NULL, + updated_at = max(updated_at, ${now}) WHERE org_id = ${orgId} AND trigger_id = ${id}`; + return true; + } + if (row !== undefined && row.enabled === 1) { + const stored = yield* decodeSchedule(row.schedule); + // A fired `once` keeps its runAt with next_run_at cleared; re-syncing must not refire it. + if (stored.type === "once" && Date.parse(stored.runAt) === runAt) return false; + } + const schedule = yield* encodeSchedule({ type: "once", runAt: iso(runAt) }); + const subject = yield* encodeSubject({ type: "deferral", itemId, phase }); + const inserted = yield* sql` + INSERT INTO kin_triggers (trigger_id, org_id, subject_json, schedule_json, time_zone, enabled, + next_run_at, last_fire_id, created_at, updated_at) + VALUES (${id}, ${orgId}, ${subject}, ${schedule}, ${timeZone}, 1, ${runAt}, NULL, ${now}, ${now}) + ON CONFLICT DO NOTHING RETURNING trigger_id + `; + if (inserted.length === 0) + yield* sql`UPDATE kin_triggers SET subject_json = ${subject}, schedule_json = ${schedule}, + time_zone = ${timeZone}, enabled = 1, next_run_at = ${runAt}, + updated_at = max(updated_at, ${now}) + WHERE org_id = ${orgId} AND trigger_id = ${id}`; + return true; + }); + + const syncCard = Effect.fn("KinTriggerService.syncCard")(function* ( + orgId: KinOrgId, + itemId: KinMemoryItemId, + item: SyncItem | undefined, + plan: DeferralPlan, + timeZone: string, + now: number, + ) { + const widgetId = KinWidgetId.make(deferralWidgetId(orgId, itemId)); + const existing = yield* repo.getWidget({ orgId, widgetId }); + const at = iso(now); + if (!plan.armed || plan.dueAt === null || item === undefined) { + if (Option.isNone(existing) || existing.value.closedAt !== null) return; + const widget = yield* repo.updateWidget({ + ...existing.value, + expectedRevision: existing.value.revision, + closedAt: at, + updatedAt: at, + }); + return yield* publish({ type: "widget.updated", orgId, widget }); + } + const state: KinDeferralCard = { + itemId, + title: item.title, + dueAt: iso(plan.dueAt), + onDue: plan.onDue, + text: confirmText(plan.dueAt, plan.onDue, timeZone), + }; + if (Option.isSome(existing)) { + const widget = yield* repo.updateWidget({ + ...existing.value, + expectedRevision: existing.value.revision, + state, + closedAt: null, + updatedAt: at, + }); + return yield* publish({ type: "widget.updated", orgId, widget }); + } + // Only kin_defer items name a chat; other deferrals arm without a card. + if (item.chat === undefined) return; + const chatId = KinChatId.make(item.chat); + const [chat] = yield* sql`SELECT 1 FROM kin_chats + WHERE org_id = ${orgId} AND chat_id = ${chatId} ORDER BY chat_id`; + if (chat === undefined) + return yield* Effect.logWarning("Deferral chat is not in its organization", { + orgId, + itemId, + }); + const message = yield* repo.insertMessage({ + orgId, + chatId, + messageId: KinMessageId.make(widgetId), + author: { _tag: "system" }, + kind: "system", + body: state.text, + intent: null, + mentions: [], + replyTo: null, + widgetId: null, + floorRunId: null, + status: "posted", + sentBy: null, + clientMessageId: null, + createdAt: at, + editedAt: null, + }); + const widget = { + orgId, + chatId, + messageId: message.messageId, + widgetId, + widgetClass: "native" as const, + type: "deferral", + state, + source: null, + feed: null, + awaiting: [], + pinnedAt: null, + closedAt: null, + updatedAt: at, + }; + yield* repo.insertWidget(widget); + yield* publish({ type: "message.posted", orgId, message }); + yield* publish({ type: "widget.updated", orgId, widget: { ...widget, revision: 1 } }); + }); + + const apply = Effect.fn("KinTriggerService.apply")(function* ( + orgId: KinOrgId, + itemId: KinMemoryItemId, + item: SyncItem | undefined, + ) { + const plan = item === undefined ? disarmedPlan : planDeferral(item); + const timeZone = yield* cache.ownerTimeZone(orgId); + const now = yield* Clock.currentTimeMillis; + return yield* sql.withTransaction( + Effect.gen(function* () { + const [org] = yield* sql`SELECT 1 FROM kin_orgs WHERE org_id = ${orgId} ORDER BY org_id`; + if (org === undefined) return yield* Effect.fail("unknown_org" as const); + let changed = false; + for (const phase of phases) { + const runAt = plan.phases.find((entry) => entry.phase === phase)?.runAt; + if (yield* syncTrigger(orgId, itemId, phase, runAt, timeZone, now)) changed = true; + } + const [run] = yield* sql<{ state: string; dueAt: number | null; onDue: string }>` + SELECT state, due_at AS "dueAt", on_due AS "onDue" FROM kin_deferral_runs + WHERE org_id = ${orgId} AND item_id = ${itemId} ORDER BY item_id + `; + let result: SyncResult = "unchanged"; + if (plan.armed && item !== undefined) { + const snapshot = yield* encodeSnapshot(deferralSnapshot(item)); + const inserted = yield* sql` + INSERT INTO kin_deferral_runs (org_id, item_id, state, due_at, on_due, snapshot_json, updated_at) + VALUES (${orgId}, ${itemId}, 'armed', ${plan.dueAt}, ${plan.onDue}, ${snapshot}, ${now}) + ON CONFLICT DO NOTHING RETURNING item_id + `; + if (inserted.length === 1) result = "armed"; + else if ( + changed || + run?.state === "disarmed" || + run?.dueAt !== plan.dueAt || + run?.onDue !== plan.onDue + ) { + yield* sql`UPDATE kin_deferral_runs SET state = 'armed', due_at = ${plan.dueAt}, + on_due = ${plan.onDue}, snapshot_json = ${snapshot}, updated_at = ${now} + WHERE org_id = ${orgId} AND item_id = ${itemId}`; + result = "armed"; + } + } else if (changed || (run !== undefined && run.state !== "disarmed")) { + yield* sql`UPDATE kin_deferral_runs SET state = 'disarmed', updated_at = ${now} + WHERE org_id = ${orgId} AND item_id = ${itemId} AND state <> 'disarmed'`; + result = "disarmed"; + } + if (result !== "unchanged") yield* syncCard(orgId, itemId, item, plan, timeZone, now); + return result; + }), + ); + }); + + const wrap = (orgId: KinOrgId) => + Effect.mapError( + (cause: unknown) => + new KinTriggerSyncError({ + orgId, + cause: isSqlError(cause) ? toPersistenceSqlError("KinTriggerService.sync")(cause) : cause, + }), + ); + + const syncItem = Effect.fn("KinTriggerService.syncItem")(function* (item: SyncItem) { + if (item.kind !== "deferral") return "unchanged" as const; + return yield* apply(item.orgId, item.id, item).pipe(wrap(item.orgId)); + }); + + return KinTriggerService.of({ + syncItem, + syncOrg: Effect.fn("KinTriggerService.syncOrg")(function* (orgId, items) { + const present = new Set(); + for (const item of items) { + if (item.orgId !== orgId || item.kind !== "deferral") continue; + present.add(item.id); + yield* syncItem(item); + } + const runs = yield* sql<{ itemId: KinMemoryItemId }>` + SELECT item_id AS "itemId" FROM kin_deferral_runs + WHERE org_id = ${orgId} AND state <> 'disarmed' ORDER BY item_id + `.pipe(wrap(orgId)); + for (const run of runs) + if (!present.has(run.itemId)) yield* apply(orgId, run.itemId, undefined).pipe(wrap(orgId)); + }), + }); +}); + +export const layer = Layer.effect(KinTriggerService, make).pipe(Layer.provide(MemoryCache.layer)); + +/** Feeds each front-matter cache snapshot into deferral arming. */ +export const syncHooksLayer = Layer.effect( + Memory.MemorySyncHooks, + Effect.gen(function* () { + const service = yield* KinTriggerService; + return Memory.MemorySyncHooks.of({ + syncItems: Effect.fn("KinTriggerService.syncItems")(function* (orgId, items) { + yield* service + .syncOrg(orgId, items) + .pipe(Effect.mapError((cause) => new Memory.MemorySyncHookError({ orgId, cause }))); + }), + }); + }), +); diff --git a/apps/server/src/kin/triggers/deferrals.test.ts b/apps/server/src/kin/triggers/deferrals.test.ts new file mode 100644 index 000000000000..7bc6103ec78c --- /dev/null +++ b/apps/server/src/kin/triggers/deferrals.test.ts @@ -0,0 +1,128 @@ +import { assert, it } from "@effect/vitest"; +import { + KinAgentId, + KinChatId, + KinEvent, + KinEventId, + KinMemberId, + KinMessageId, + KinPersonId, + KinWakeupId, + KinWidgetId, +} from "@t3tools/contracts"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Schema from "effect/Schema"; +import * as SqlClient from "effect/sql/SqlClient"; +import * as TestClock from "effect/testing/TestClock"; + +import * as Repository from "../chat/KinChatRepository.ts"; +import * as Queue from "../lead/KinEventQueue.ts"; +import * as MemoryWriter from "../memory/MemoryWriter.ts"; +import * as Deferrals from "./deferrals.ts"; +import * as TriggerService from "./KinTriggerService.ts"; +import { fixture, item, orgId, otherOrg, seed } from "./routines.testkit.ts"; + +const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); +const decodeEvent = Schema.decodeSync(KinEvent); +const deferral = item("def-1", { + kind: "deferral", + path: "deferrals/def-1.md", + due: "2026-11-13T09:00+05:30", + on_due: "start", + chat: KinChatId.make("chat-a"), +}); +const widgetId = KinWidgetId.make(`deferral:${orgId}:def-1`); + +it.effect("applies verified owner taps on the confirm card and ignores forged ones", () => + Effect.gen(function* () { + yield* seed(); + yield* TestClock.setTime(Date.parse("2026-11-09T09:00:00.000Z")); + const sql = yield* SqlClient.SqlClient; + const repo = yield* Repository.KinChatRepository; + const queue = yield* Queue.KinEventQueue; + const deferrals = yield* Deferrals.Deferrals; + yield* (yield* TriggerService.KinTriggerService).syncItem(deferral); + const staged: MemoryWriter.MemoryChange[] = []; + const writer = Layer.mock(MemoryWriter.MemoryWriter)({ + stage: (_org, _wakeup, change) => Effect.sync(() => void staged.push(change)), + }); + const tapOnce = Effect.fn("test.deferralTap")(function* (actionId: string, label: string) { + const memberId = "owner-member-a"; + // Stands in for the gated dispatcher: chat act refuses deferral taps today. + const message = yield* repo.insertMessage({ + orgId, + chatId: KinChatId.make("chat-a"), + messageId: KinMessageId.make(`tap-${actionId}-${label}`), + author: { + _tag: "human", + personId: KinPersonId.make("owner-a"), + memberId: KinMemberId.make(memberId), + }, + kind: "widget_action", + body: encodeJson({ widgetId, revision: 1, actionId, value: "def-1" }), + intent: null, + mentions: [], + replyTo: KinMessageId.make(widgetId), + widgetId, + floorRunId: null, + status: "posted", + sentBy: KinPersonId.make("owner-a"), + clientMessageId: { kind: "act", id: `${actionId}-${label}` }, + createdAt: "2026-11-09T09:00:00.000Z", + editedAt: null, + }); + const eventId = `${actionId}-${label}`; + yield* queue.enqueue( + decodeEvent({ + _tag: "widget.action", + orgId, + eventId, + agentId: "lead-a", + receivedAt: "2026-11-09T09:00:00.000Z", + dedupeKey: eventId, + provenance: { _tag: "human", personId: "owner-a", memberId }, + chatId: "chat-a", + messageId: message.messageId, + actionId, + }), + ); + yield* TestClock.adjust("20 seconds"); + const wakeupId = KinWakeupId.make(`wake-${eventId}`); + yield* queue.claim({ orgId, agentId: KinAgentId.make("lead-a"), wakeupId, model: "fixture" }); + if (label === "demoted") + yield* sql`UPDATE kin_chat_members SET role = 'member' WHERE org_id = ${orgId} AND member_id = ${memberId}`; + const result = yield* deferrals + .act(orgId, wakeupId, KinEventId.make(eventId)) + .pipe(Effect.provide(writer), Effect.result); + const forged = yield* deferrals + .act(otherOrg, wakeupId, KinEventId.make(eventId)) + .pipe(Effect.provide(writer), Effect.flip); + assert.equal(forged._tag, "DeferralError"); + yield* queue.finish({ orgId, wakeupId, status: "completed" }); + return result; + }); + const tap = (actionId: string, label: string) => Effect.scoped(tapOnce(actionId, label)); + + const remind = yield* tap("remind", "owner"); + assert.equal(remind._tag === "Success" && remind.success.action, "remind"); + assert.lengthOf(staged, 1); + assert.equal(staged[0]?.sourceEventId, "remind-owner"); + assert.include(staged[0]!.content, "on_due: remind"); + + const change = yield* tap("change", "owner"); + assert.equal(change._tag === "Success" && change.success.action, "change"); + assert.lengthOf(staged, 1); + + const member = yield* tap("remind", "demoted"); + assert.equal(member._tag, "Failure"); + assert.lengthOf(staged, 1); + }).pipe( + Effect.provide( + Deferrals.layer.pipe( + Layer.provideMerge(TriggerService.layer), + Layer.provideMerge(fixture([deferral])), + ), + ), + ), +); diff --git a/apps/server/src/kin/triggers/deferrals.ts b/apps/server/src/kin/triggers/deferrals.ts new file mode 100644 index 000000000000..829fb11db2c2 --- /dev/null +++ b/apps/server/src/kin/triggers/deferrals.ts @@ -0,0 +1,164 @@ +import { + KinChatId, + KinDeferralCard, + KinEventId, + KinMemoryItemId, + KinOrgId, + KinTriggerId, + type MemoryItemHead, +} from "@t3tools/contracts"; +import * as Context from "effect/Context"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Schema from "effect/Schema"; +import * as SqlClient from "effect/sql/SqlClient"; +import { stringify } from "yaml"; + +import * as Repository from "../chat/KinChatRepository.ts"; +import * as Memory from "../memory/Memory.ts"; +import * as MemoryWriter from "../memory/MemoryWriter.ts"; +import { memoryDateMillis } from "../memory/frontMatter.ts"; +import { deferralCardActions } from "../widgets/deferralCard.ts"; +import { verifyOwnerTap } from "./ownerCheck.ts"; + +const HEADS_UP_MS = 30 * 60_000; +export type OnDue = KinDeferralCard["onDue"]; +export type DeferralPhase = "heads_up" | "due"; + +export interface DeferralPlan { + readonly armed: boolean; + readonly dueAt: number | null; + readonly onDue: OnDue; + readonly phases: ReadonlyArray<{ readonly phase: DeferralPhase; readonly runAt: number }>; +} + +export const deferralTriggerId = (itemId: string, phase: DeferralPhase) => + KinTriggerId.make(`deferral:${itemId}:${phase}`); +export const deferralWidgetId = (orgId: string, itemId: string) => `deferral:${orgId}:${itemId}`; + +// A deferral without on_due only reminds: silence never starts work. +export function planDeferral( + item: MemoryItemHead & { readonly duplicate?: boolean }, +): DeferralPlan { + const onDue = item.on_due ?? "remind"; + const due = memoryDateMillis(item.due); + const dueAt = Number.isFinite(due) ? due : null; + const armed = + item.kind === "deferral" && + item.status === "open" && + item.invalid_at === null && + item.superseded_by === null && + item.duplicate !== true && + dueAt !== null; + if (!armed || dueAt === null) return { armed: false, dueAt, onDue, phases: [] }; + const dueFire = { phase: "due" as const, runAt: dueAt }; + return { + armed, + dueAt, + onDue, + phases: + onDue === "start" ? [{ phase: "heads_up", runAt: dueAt - HEADS_UP_MS }, dueFire] : [dueFire], + }; +} + +/** The item half of the recheck baseline; TRIG-8 adds the GitHub half. */ +export const DeferralSnapshot = Schema.Struct({ + recordedAt: Schema.String, + supersededBy: Schema.NullOr(KinMemoryItemId), + links: Schema.Array(Schema.String), +}); +export const deferralSnapshot = (item: MemoryItemHead): typeof DeferralSnapshot.Type => ({ + recordedAt: item.recorded_at, + supersededBy: item.superseded_by, + links: item.links, +}); + +const then: Record = { + start: "I'll start then.", + remind: "I'll remind you then.", + ask: "I'll ask you then.", + chase: "I'll chase it then.", +}; + +export function confirmText(dueAt: number, onDue: OnDue, timeZone: string): string { + const parts = Object.fromEntries( + new Intl.DateTimeFormat("en-GB", { + timeZone, + weekday: "short", + day: "numeric", + month: "short", + hour: "numeric", + minute: "2-digit", + hourCycle: "h23", + }) + .formatToParts(dueAt) + .map((part) => [part.type, part.value]), + ); + return `Deferred to ${parts.weekday} ${parts.day} ${parts.month}, ${Number(parts.hour)}:${parts.minute}. ${then[onDue]}`; +} + +export class DeferralError extends Schema.TaggedError()("DeferralError", { + orgId: KinOrgId, + cause: Schema.Defect(), +}) {} + +const decodeCard = Schema.decodeUnknownEffect(KinDeferralCard); +const decodeAction = Schema.decodeUnknownEffect( + Schema.Struct({ actionId: Schema.Literals(deferralCardActions), value: KinMemoryItemId }), +); + +export class Deferrals extends Context.Service< + Deferrals, + { + /** Applies a verified owner tap on a deferral card. [Change] hands the item to the lead. */ + readonly act: ( + orgId: KinOrgId, + wakeupId: string, + eventId: KinEventId, + ) => Effect.Effect< + { + readonly chatId: KinChatId; + readonly itemId: KinMemoryItemId; + readonly action: (typeof deferralCardActions)[number]; + }, + DeferralError, + MemoryWriter.MemoryWriter + >; + } +>()("t3/kin/triggers/deferrals") {} + +const make = Effect.gen(function* () { + const memory = yield* Memory.Memory; + const sql = yield* SqlClient.SqlClient; + const repo = yield* Repository.KinChatRepository; + return Deferrals.of({ + act: Effect.fn("Deferrals.act")((orgId, wakeupId, eventId) => + Effect.gen(function* () { + const writer = yield* MemoryWriter.MemoryWriter; + const tap = yield* verifyOwnerTap(orgId, wakeupId, eventId, "deferral").pipe( + Effect.provideService(SqlClient.SqlClient, sql), + Effect.provideService(Repository.KinChatRepository, repo), + ); + const action = yield* decodeAction(tap.action); + const card = yield* decodeCard(tap.widget.state); + if (card.itemId !== action.value) return yield* Effect.fail("unknown_item" as const); + if (action.actionId === "remind") { + const item = yield* memory.readItemQuietly(orgId, card.itemId); + if (item.head.kind !== "deferral" || item.head.status !== "open") + return yield* Effect.fail("not_open" as const); + if (item.head.on_due !== "remind") { + const { orgId: _org, path, ...frontMatter } = item.head; + yield* writer.stage(orgId, wakeupId, { + path, + content: `---\n${stringify({ ...frontMatter, on_due: "remind" })}---\n${item.body}`, + sourceEventId: eventId, + }); + } + } + return { chatId: tap.chatId, itemId: card.itemId, action: action.actionId }; + }).pipe(Effect.mapError((cause) => new DeferralError({ orgId, cause }))), + ), + }); +}); + +export const layer = Layer.effect(Deferrals, make); diff --git a/apps/server/src/kin/triggers/ownerCheck.ts b/apps/server/src/kin/triggers/ownerCheck.ts index f31102d5990c..d554c4d7d843 100644 --- a/apps/server/src/kin/triggers/ownerCheck.ts +++ b/apps/server/src/kin/triggers/ownerCheck.ts @@ -37,12 +37,20 @@ type Selection = typeof Selection.Type; const decodeCard = Schema.decodeUnknownEffect(KinOwnerCheckCard); const decodeEvent = Schema.decodeUnknownEffect(Schema.fromJsonString(KinEvent)); const decodeAction = Schema.decodeUnknownEffect( + Schema.Struct({ + widgetId: KinWidgetId, + revision: Schema.Int, + actionId: Schema.Literals(["keep", "update", "drop"]), + value: KinMemoryItemId, + }), +); +const decodeTap = Schema.decodeUnknownEffect( Schema.fromJsonString( Schema.Struct({ widgetId: KinWidgetId, revision: Schema.Int, - actionId: Schema.Literals(["keep", "update", "drop"]), - value: KinMemoryItemId, + actionId: Schema.String, + value: Schema.optional(Schema.Unknown), }), ), ); @@ -95,6 +103,66 @@ export function pickOwnerCheckItems( .map(({ item, rank }) => ({ itemId: item.id, reason: reasons[rank] ?? "no_evidence" })); } +/** Verifies a claimed widget tap as the org owner's own action on an open card of `type`. */ +export const verifyOwnerTap = Effect.fn("OwnerCheck.verifyOwnerTap")(function* ( + orgId: KinOrgId, + wakeupId: string, + eventId: KinEventId, + type: string, +) { + const sql = yield* SqlClient.SqlClient; + const repo = yield* Repository.KinChatRepository; + return yield* sql + .withTransaction( + Effect.gen(function* () { + const [row] = yield* sql<{ + json: string; + }>`SELECT e.json FROM kin_events e JOIN kin_wakeups w ON w.org_id = e.org_id AND w.wakeup_id = e.wakeup_id WHERE e.org_id = ${orgId} AND e.event_id = ${eventId} AND e.wakeup_id = ${wakeupId} AND e.state = 'claimed' AND w.status = 'running' ORDER BY e.event_id`; + if (row === undefined) return yield* Effect.fail("unclaimed_action" as const); + const event = yield* decodeEvent(row.json); + if ( + event.orgId !== orgId || + event.eventId !== eventId || + event._tag !== "widget.action" || + event.provenance._tag !== "human" + ) + return yield* Effect.fail("not_owner" as const); + const message = yield* repo.getMessage({ orgId, messageId: event.messageId }); + if ( + Option.isNone(message) || + message.value.chatId !== event.chatId || + message.value.kind !== "widget_action" || + message.value.authorRole !== "owner" || + message.value.author._tag !== "human" || + message.value.author.personId !== event.provenance.personId || + message.value.author.memberId !== event.provenance.memberId + ) + return yield* Effect.fail("not_owner" as const); + const owners = + yield* sql`SELECT m.member_id FROM kin_chat_members m JOIN kin_agents a ON a.org_id = m.org_id AND a.owner_person_id = m.person_id WHERE m.org_id = ${orgId} AND m.member_id = ${event.provenance.memberId} AND m.chat_id = ${event.chatId} AND m.person_id = ${event.provenance.personId} AND m.role = 'owner' AND m.left_at IS NULL AND a.agent_id = ${event.agentId} AND a.retired_at IS NULL ORDER BY m.member_id`; + if (owners.length === 0) return yield* Effect.fail("not_owner" as const); + const action = yield* decodeTap(message.value.body); + const widget = yield* repo.getWidget({ orgId, widgetId: action.widgetId }); + if ( + Option.isNone(widget) || + widget.value.type !== type || + widget.value.chatId !== event.chatId || + message.value.widgetId !== action.widgetId || + widget.value.closedAt !== null || + widget.value.revision !== action.revision || + event.actionId !== action.actionId + ) + return yield* Effect.fail("invalid_card" as const); + return { action, chatId: event.chatId, widget: widget.value }; + }), + ) + .pipe( + Effect.mapError((cause) => + isSqlError(cause) ? toPersistenceSqlError("OwnerCheck.verifyOwnerTap")(cause) : cause, + ), + ); +}); + export class OwnerCheckError extends Schema.TaggedError()("OwnerCheckError", { orgId: KinOrgId, cause: Schema.Defect(), @@ -233,62 +301,17 @@ const make = Effect.gen(function* () { orgId, Effect.gen(function* () { const writer = yield* MemoryWriter.MemoryWriter; - const verified = yield* sql - .withTransaction( - Effect.gen(function* () { - const [row] = yield* sql<{ - json: string; - }>`SELECT e.json FROM kin_events e JOIN kin_wakeups w ON w.org_id = e.org_id AND w.wakeup_id = e.wakeup_id WHERE e.org_id = ${orgId} AND e.event_id = ${eventId} AND e.wakeup_id = ${wakeupId} AND e.state = 'claimed' AND w.status = 'running' ORDER BY e.event_id`; - if (row === undefined) return yield* Effect.fail("unclaimed_action"); - const event = yield* decodeEvent(row.json); - if ( - event.orgId !== orgId || - event.eventId !== eventId || - event._tag !== "widget.action" || - event.provenance._tag !== "human" - ) - return yield* Effect.fail("not_owner"); - const message = yield* repo.getMessage({ orgId, messageId: event.messageId }); - if ( - Option.isNone(message) || - message.value.chatId !== event.chatId || - message.value.kind !== "widget_action" || - message.value.authorRole !== "owner" || - message.value.author._tag !== "human" || - message.value.author.personId !== event.provenance.personId || - message.value.author.memberId !== event.provenance.memberId - ) - return yield* Effect.fail("not_owner"); - const owners = - yield* sql`SELECT m.member_id FROM kin_chat_members m JOIN kin_agents a ON a.org_id = m.org_id AND a.owner_person_id = m.person_id WHERE m.org_id = ${orgId} AND m.member_id = ${event.provenance.memberId} AND m.chat_id = ${event.chatId} AND m.person_id = ${event.provenance.personId} AND m.role = 'owner' AND m.left_at IS NULL AND a.agent_id = ${event.agentId} AND a.retired_at IS NULL ORDER BY m.member_id`; - if (owners.length === 0) return yield* Effect.fail("not_owner"); - const action = yield* decodeAction(message.value.body); - const widget = yield* repo.getWidget({ orgId, widgetId: action.widgetId }); - if ( - Option.isNone(widget) || - widget.value.type !== "owner_check" || - widget.value.chatId !== event.chatId || - message.value.widgetId !== action.widgetId || - widget.value.closedAt !== null || - widget.value.revision !== action.revision || - event.actionId !== action.actionId - ) - return yield* Effect.fail("invalid_card"); - const card = yield* decodeCard(widget.value.state); - if ( - !card.items.some( - (item) => item.itemId === action.value && item.handled === undefined, - ) - ) - return yield* Effect.fail("unknown_item"); - return { action, chatId: event.chatId, widget: widget.value, card }; - }), - ) - .pipe( - Effect.mapError((cause) => - isSqlError(cause) ? toPersistenceSqlError("OwnerCheck.act")(cause) : cause, - ), - ); + const tap = yield* verifyOwnerTap(orgId, wakeupId, eventId, "owner_check").pipe( + Effect.provideService(SqlClient.SqlClient, sql), + Effect.provideService(Repository.KinChatRepository, repo), + ); + const action = yield* decodeAction(tap.action); + const card = yield* decodeCard(tap.widget.state); + if ( + !card.items.some((item) => item.itemId === action.value && item.handled === undefined) + ) + return yield* Effect.fail("unknown_item"); + const verified = { action, chatId: tap.chatId, widget: tap.widget, card }; const item = yield* memory.readItemQuietly(orgId, verified.action.value); if (verified.action.actionId !== "update") { const { orgId: _org, path, ...frontMatter } = item.head; diff --git a/apps/server/src/kin/widgets/deferralCard.ts b/apps/server/src/kin/widgets/deferralCard.ts new file mode 100644 index 000000000000..c0e644b6879a --- /dev/null +++ b/apps/server/src/kin/widgets/deferralCard.ts @@ -0,0 +1,4 @@ +// Taps need the owner-tap dispatcher that also gates the owner check; see the +// deferral card release gate in docs/kin/specs/triggers.md. +export const deferralCardActionsReady = false; +export const deferralCardActions = ["change", "remind"] as const; diff --git a/apps/server/src/kin/widgets/registry.ts b/apps/server/src/kin/widgets/registry.ts index 31b038ab429b..e4da474d0220 100644 --- a/apps/server/src/kin/widgets/registry.ts +++ b/apps/server/src/kin/widgets/registry.ts @@ -1,10 +1,16 @@ -import { KinChatError, KinTaskCardState, KinOwnerCheckCard } from "@t3tools/contracts"; +import { + KinChatError, + KinDeferralCard, + KinTaskCardState, + KinOwnerCheckCard, +} from "@t3tools/contracts"; import * as Effect from "effect/Effect"; import * as Schema from "effect/Schema"; const schemas = new Map>([ ["task", KinTaskCardState], ["owner_check", KinOwnerCheckCard], + ["deferral", KinDeferralCard], ]); export const validateState = Effect.fn("KinWidgetRegistry.validateState")(function* ( diff --git a/docs/kin/specs/triggers.md b/docs/kin/specs/triggers.md index 69d876d00f1e..852d9f095ebb 100644 --- a/docs/kin/specs/triggers.md +++ b/docs/kin/specs/triggers.md @@ -203,9 +203,20 @@ Arming comes from memory. When the front-matter cache (LEAD) sees a `deferrals/* | `ask` | `due` only | post a decision card | | `chase` | `due` only | ping the promiser (ping rules) | -Item edits move or disarm the triggers: a new `due` re-arms; `status` other than `open` or a set `invalid_at` disables them. A due time already past at save fires at once, marked late; no "pick a future time" error. +Item edits move or disarm the triggers: a new `due` re-arms; `status` other than `open` or a set `invalid_at` disables them. A due time already past at save fires at once, marked late; no "pick a future time" error. A missing `on_due` means `remind`, so silence never starts work. -**Confirm.** When the lead calls `kin_defer` (LEAD), Kin writes the item, arms the triggers, and the lead posts a `KinDeferralCard` widget (CHAT envelope): "Deferred to Fri 13 Nov, 9:00. I'll start then." [Change] [Just remind me]. [Just remind me] sets `on_due: remind`, and the triggers re-arm. +The cache hook is `MemorySyncHooks` in [`Memory.ts`](../../../apps/server/src/kin/memory/Memory.ts): every newly loaded snapshot goes to `KinTriggerService.syncOrg`, which also disarms armed deferrals missing from the snapshot or sharing a duplicate id. A failed sync retries on the next load, and `trigger_reconcile` remains the backstop. A commit to the default branch moves the cache to the new head and reloads it, so a `kin_defer` item arms when its wake-up commits, not at the next wake-up; shadow (L0) commits never arm. Trigger ids are `deferral::heads_up|due`. Re-syncing an unchanged `due` writes nothing, so a fired `once` is never re-armed. The run row in `kin_deferral_runs` (provisional migration K017) holds the snapshot and an `armed`/`disarmed` state; TRIG-8 owns the due-flow states. The snapshot holds the item half only (`recorded_at`, `superseded_by`, links). There is no GitHub reader in Kin yet, so TRIG-8 must add the GitHub half (issue/PR state, assignees, linked PRs) at arm time before the due flow ships. + +**Confirm.** When the lead calls `kin_defer` (LEAD), Kin writes the item, arms the triggers, and the lead posts a `KinDeferralCard` widget (CHAT envelope): "Deferred to Fri 13 Nov, 9:00. I'll start then." [Change] [Just remind me]. [Just remind me] sets `on_due: remind`, and the triggers re-arm. [Change] writes nothing: it hands the item to the lead, which asks the owner what to change, marks the old item `cancelled` and calls `kin_defer` for the new one. + +Code posts the card, never the model. It goes to the item's `chat` when that chat belongs to the item's org; deferrals without a chat arm without a card. Times use the owner's zone. A re-arm updates the card text in place, a disarm closes the card, and reopening the item reopens it. The card awaits nobody. + +**Deferral card release gate (TRIG-7):** cards post live, but `KinChatService.act` refuses deferral-card taps (`deferralCardActionsReady = false`) until the owner-tap dispatcher from the owner-check gate exists. `Deferrals.act` already verifies the tap with the same `verifyOwnerTap` as the owner check. Before enabling taps: + +- the owner-check gate's dispatcher steps must land (chat act enqueues `widget.action`; `WakeupRunner` intercepts card actions without showing them to the model); +- `WakeupRunner` must run `Deferrals.act` for `deferral` actions, then `MemoryWriter.commitWakeup` (the commit re-arms through the cache hook), then queue `finish`. [Change] goes to the lead as an owner message about the item; +- production `MemoryWriterAuthority.resolve` must grant `kind: "deferral_card"` (item id, action `remind`) only after verifying the claimed owner tap. With that grant, the writer lets `on_due` change, and only to `remind`; +- web and mobile must render the native card and its closed state. **Flow for `start`** (`kin_deferral_runs.state`): diff --git a/packages/contracts/src/kinLead.ts b/packages/contracts/src/kinLead.ts index 3596dc22ab96..1c7c00c6d2ac 100644 --- a/packages/contracts/src/kinLead.ts +++ b/packages/contracts/src/kinLead.ts @@ -142,6 +142,15 @@ export const WorkerReport = Schema.Struct({ }); export type WorkerReport = typeof WorkerReport.Type; +export const KinDeferralCard = Schema.Struct({ + itemId: KinMemoryItemId, + title: Schema.String, + dueAt: Schema.toEncoded(CanonicalUtcTimestamp), + onDue: Schema.Literals(["remind", "start", "ask", "chase"]), + text: Schema.String, +}); +export type KinDeferralCard = typeof KinDeferralCard.Type; + const EventBase = { orgId: KinOrgId, eventId: KinEventId, @@ -205,7 +214,7 @@ export const KinEvent = Schema.Union([ Schema.Array( Schema.Struct({ routine: KinLeadRoutine, - dueAt: CanonicalUtcTimestamp, + dueAt: Schema.toEncoded(CanonicalUtcTimestamp), }), ), ), From 2b20cb339cec31aa4c340d1b151812430c676d87 Mon Sep 17 00:00:00 2001 From: GLDRoger <130458023+GLDRoger@users.noreply.github.com> Date: Sun, 8 Nov 2026 18:56:29 +0530 Subject: [PATCH 2/4] fix(kin): harden deferral arming from review (TRIG-7) - Reserve the deferral widget type from upserts, and only count taps on the code-posted card id in Deferrals.act. - Leave deferrals unarmed when any fire would land before 1970, and limit kin_defer due dates to 2000-2099. - Sync one org with a single stored-state query, skip items already in step, read the owner zone once, and log and continue past failing items. - Move once-per-head tracking, retry and duplicate handling into the hooks layer; Memory.load makes one hook call. - Compare the writer's immutable fields over both items' keys, and add writer scenarios for the remind exception's source checks. - Spec TRIG-8's handling of stale and over-grace fires. - Revert the unrelated foldedRoutines dueAt encoding change. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/chat/KinChatService.ts | 6 +- apps/server/src/kin/lead/LeadMemory.test.ts | 2 +- apps/server/src/kin/lead/LeadMemory.ts | 5 +- apps/server/src/kin/memory/Memory.ts | 56 ++--- .../src/kin/memory/MemoryWriter.test.ts | 27 ++- apps/server/src/kin/memory/MemoryWriter.ts | 7 +- .../kin/triggers/KinTriggerService.test.ts | 66 +++++- .../src/kin/triggers/KinTriggerService.ts | 199 ++++++++++++------ .../server/src/kin/triggers/deferrals.test.ts | 54 ++++- apps/server/src/kin/triggers/deferrals.ts | 20 +- docs/kin/specs/triggers.md | 9 +- packages/contracts/src/kinLead.ts | 2 +- 12 files changed, 320 insertions(+), 133 deletions(-) diff --git a/apps/server/src/kin/chat/KinChatService.ts b/apps/server/src/kin/chat/KinChatService.ts index dc8b9119486e..5170346f48f2 100644 --- a/apps/server/src/kin/chat/KinChatService.ts +++ b/apps/server/src/kin/chat/KinChatService.ts @@ -950,7 +950,11 @@ const make = Effect.gen(function* () { reason: "use_approvals", message: "Use the signed approvals service.", }); - if (input.type === "owner_check" || (input.type === "task" && input.widgetId === undefined)) + if ( + input.type === "owner_check" || + input.type === "deferral" || + (input.type === "task" && input.widgetId === undefined) + ) return yield* notAllowed; let state = yield* validateState(input.type, input.state); let widget: KinWidget; diff --git a/apps/server/src/kin/lead/LeadMemory.test.ts b/apps/server/src/kin/lead/LeadMemory.test.ts index b9ece593335c..01541b81f2a3 100644 --- a/apps/server/src/kin/lead/LeadMemory.test.ts +++ b/apps/server/src/kin/lead/LeadMemory.test.ts @@ -481,7 +481,7 @@ it.live( .pipe(Effect.flip)).reason, "not_found", ); - for (const due of ["bad", "2026-02-30", "2026-11-13T09:00:00"]) + for (const due of ["bad", "2026-02-30", "2026-11-13T09:00:00", "1969-12-31", "0000-01-01"]) assert.strictEqual( (yield* decodeDefer({ ...deferred, due }).pipe(Effect.result))._tag, "Failure", diff --git a/apps/server/src/kin/lead/LeadMemory.ts b/apps/server/src/kin/lead/LeadMemory.ts index 9c98977df9f4..78bb082da6bc 100644 --- a/apps/server/src/kin/lead/LeadMemory.ts +++ b/apps/server/src/kin/lead/LeadMemory.ts @@ -35,6 +35,9 @@ const date = Schema.String.check( expected: "a date or timestamp with explicit offset", }), ); +const deferDue = date.check( + Schema.makeFilter((value) => /^20\d\d-/.test(value), { expected: "a date in 2000-2099" }), +); const itemId = KinMemoryItemId.check(Schema.isPattern(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,199}$/)); export const SearchInput = Schema.Struct({ kind: Schema.optional(MemoryItemFrontMatter.fields.kind), @@ -65,7 +68,7 @@ export const WriteInput = Schema.Struct({ export const DeferInput = Schema.Struct({ itemId: Schema.optional(itemId), what: TrimmedNonEmptyString.check(Schema.isMaxLength(8000)), - due: date, + due: deferDue, onDue: Schema.Literals(["remind", "start", "ask", "chase"]), chatId: KinChatId, sourceEventId: TrimmedNonEmptyString, diff --git a/apps/server/src/kin/memory/Memory.ts b/apps/server/src/kin/memory/Memory.ts index f788121b6fde..cc6ca4aedc0c 100644 --- a/apps/server/src/kin/memory/Memory.ts +++ b/apps/server/src/kin/memory/Memory.ts @@ -21,7 +21,6 @@ import * as DateTime from "effect/DateTime"; import * as Effect from "effect/Effect"; import * as FileSystem from "effect/FileSystem"; import * as Layer from "effect/Layer"; -import * as Option from "effect/Option"; import * as Path from "effect/Path"; import * as Schema from "effect/Schema"; import * as Semaphore from "effect/Semaphore"; @@ -130,21 +129,18 @@ export class MemoryRecoveryHooks extends Context.Service< } >()("t3/kin/memory/Memory/MemoryRecoveryHooks") {} -export class MemorySyncHookError extends Schema.TaggedError()( - "MemorySyncHookError", - { orgId: Schema.String, cause: Schema.Defect() }, -) {} +export interface MemorySyncSnapshot { + readonly head: string; + readonly items: ReadonlyArray; + readonly duplicateIds: ReadonlySet; +} -/** Receives every newly loaded snapshot; must be idempotent, since a failure retries on the next load. */ -export class MemorySyncHooks extends Context.Service< - MemorySyncHooks, - { - readonly syncItems: ( - orgId: KinOrgId, - items: ReadonlyArray, - ) => Effect.Effect; - } ->()("t3/kin/memory/Memory/MemorySyncHooks") {} +/** Sees every loaded snapshot and owns its own once-per-head, retry and failure handling. */ +export class MemorySyncHooks extends Context.Reference<{ + readonly syncItems: (orgId: KinOrgId, snapshot: MemorySyncSnapshot) => Effect.Effect; +}>("t3/kin/memory/Memory/MemorySyncHooks", { + defaultValue: () => ({ syncItems: () => Effect.void }), +}) {} export class Memory extends Context.Service< Memory, @@ -202,9 +198,7 @@ const folders = ["objectives", "commitments", "deferrals", "decisions", "people" const maxBlobBytes = 256 * 1024; -interface Snapshot { - readonly head: string; - readonly items: ReadonlyArray; +interface Snapshot extends MemorySyncSnapshot { readonly files: ReadonlyMap; index?: string; } @@ -236,8 +230,7 @@ const make = Effect.gen(function* () { const sql = yield* SqlClient.SqlClient; const writerLocks = new Map(); const pinnedHeads = new Map(); - const syncedHeads = new Map(); - const syncHooks = yield* Effect.serviceOption(MemorySyncHooks); + const hooks = yield* MemorySyncHooks; const withWriterLock = (orgId: KinOrgId, effect: Effect.Effect) => { let lock = writerLocks.get(orgId); if (!lock) { @@ -718,6 +711,7 @@ const make = Effect.gen(function* () { head, items, files, + duplicateIds, ...(previous?.head === head && previous.index !== undefined ? { index: previous.index } : {}), }; snapshots.set(orgId, snapshot); @@ -729,27 +723,7 @@ const make = Effect.gen(function* () { }); const load = Effect.fn("Memory.load")(function* (orgId: KinOrgId, force = false) { const snapshot = yield* loadSnapshot(orgId, force); - if (Option.isSome(syncHooks) && syncedHeads.get(orgId) !== snapshot.head) { - const counts = new Map(); - for (const { head } of snapshot.items) counts.set(head.id, (counts.get(head.id) ?? 0) + 1); - yield* syncHooks.value - .syncItems( - orgId, - snapshot.items.map(({ head }) => ({ - ...head, - duplicate: (counts.get(head.id) ?? 0) > 1, - })), - ) - .pipe( - Effect.tap(() => Effect.sync(() => syncedHeads.set(orgId, snapshot.head))), - Effect.catch((error) => - Effect.logWarning("Could not sync memory triggers; retrying on next load", { - orgId, - errorTag: error._tag, - }), - ), - ); - } + yield* hooks.syncItems(orgId, snapshot); return snapshot; }); diff --git a/apps/server/src/kin/memory/MemoryWriter.test.ts b/apps/server/src/kin/memory/MemoryWriter.test.ts index 955ed554ac08..13f18b2810bd 100644 --- a/apps/server/src/kin/memory/MemoryWriter.test.ts +++ b/apps/server/src/kin/memory/MemoryWriter.test.ts @@ -64,6 +64,8 @@ it.live.each([ "credentials", "read-during-record", "deferral-card-remind", + "deferral-plain-remind", + "deferral-card-other-item", "H3-packed-ref", "M1-unanchored", "M2-nondescendant", @@ -126,7 +128,7 @@ it.live.each([ }), ); } - if (scenario === "deferral-card-remind") { + if (scenario.startsWith("deferral-")) { yield* fs.makeDirectory(`${source}/deferrals`); yield* fs.writeFileString(`${source}/deferrals/def-001.md`, fixtureItem()); } @@ -223,9 +225,9 @@ it.live.each([ Layer.provide(Layer.succeed(Memory.MemoryRecoveryHooks, { notify: () => Effect.void })), Layer.provide( Layer.succeed(Memory.MemorySyncHooks, { - syncItems: (_org, items) => + syncItems: (_org, snapshot) => Effect.sync(() => { - synced.push(items); + synced.push(snapshot.items.map(({ head }) => head)); }), }), ), @@ -253,7 +255,7 @@ it.live.each([ scenario === "conflict" || scenario === "B5-journal" || scenario === "read-during-record" || - scenario === "deferral-card-remind" + scenario.startsWith("deferral-") ? "L1" : "L0", timeZone: "Asia/Kolkata", @@ -278,13 +280,15 @@ it.live.each([ itemId: scenario === "owner-other-item-keep" ? "other-item" : "def-001", action: scenario === "owner-drop-keep" ? "drop" : "keep", } - : scenario === "deferral-card-remind" + : scenario === "deferral-card-remind" || + scenario === "deferral-card-other-item" ? { saidBy: "fixture-owner", trust: "owner", source: "fixture-owner-message", kind: "deferral_card", - itemId: "def-001", + itemId: + scenario === "deferral-card-other-item" ? "other-item" : "def-001", action: "remind", } : { @@ -638,6 +642,17 @@ it.live.each([ ).toBe("Success"); return; } + if (scenario === "deferral-plain-remind" || scenario === "deferral-card-other-item") { + const result = yield* writer + .stage(orgId, "wake1", { + path: "deferrals/def-001.md", + content: fixtureItem({ on_due: "remind" }), + sourceEventId: "owner", + }) + .pipe(Effect.result); + expect(result._tag === "Failure" && result.failure._tag).toBe("MemoryConflict"); + return; + } if (scenario === "deferral-card-remind") { const stage = (onDue: string) => writer diff --git a/apps/server/src/kin/memory/MemoryWriter.ts b/apps/server/src/kin/memory/MemoryWriter.ts index 086f8fb38d09..6285503d6004 100644 --- a/apps/server/src/kin/memory/MemoryWriter.ts +++ b/apps/server/src/kin/memory/MemoryWriter.ts @@ -539,11 +539,12 @@ const make = Effect.gen(function* () { fm.on_due === "remind" ) mutable.add("on_due"); + const existing = new Map(Object.entries(item)); if ( - Object.entries(item).some( - ([key, value]) => + [...new Set([...existing.keys(), ...proposed.keys()])].some( + (key) => !mutable.has(key) && - JSON.stringify(value) !== JSON.stringify(proposed.get(key)), + JSON.stringify(existing.get(key)) !== JSON.stringify(proposed.get(key)), ) ) return yield* new MemoryConflict({ existingId: item.id }); diff --git a/apps/server/src/kin/triggers/KinTriggerService.test.ts b/apps/server/src/kin/triggers/KinTriggerService.test.ts index f5e9ce5fb746..6e77c48b96ce 100644 --- a/apps/server/src/kin/triggers/KinTriggerService.test.ts +++ b/apps/server/src/kin/triggers/KinTriggerService.test.ts @@ -19,6 +19,7 @@ import * as Chat from "../chat/KinChatService.ts"; import * as Hub from "../chat/KinChatHub.ts"; import * as Repository from "../chat/KinChatRepository.ts"; import * as JudgeShadow from "../floor/JudgeShadow.ts"; +import * as Memory from "../memory/Memory.ts"; import * as Persistence from "../persistence/KinPersistence.ts"; import * as TriggerService from "./KinTriggerService.ts"; import { item, orgId, otherOrg, seed } from "./routines.testkit.ts"; @@ -28,7 +29,8 @@ const now = Date.parse("2026-11-09T09:00:00.000Z"); const due = "2026-11-13T09:00+05:30"; const dueAt = Date.parse("2026-11-13T03:30:00.000Z"); -const layer = TriggerService.layer.pipe( +const layer = TriggerService.syncHooksLayer.pipe( + Layer.provideMerge(TriggerService.layer), Layer.provideMerge( Chat.layer.pipe(Layer.provide(JudgeShadow.layerOff), Layer.provideMerge(Hub.layer)), ), @@ -135,6 +137,8 @@ it.effect.each([ ["done", { status: "done" }], ["cancelled", { status: "cancelled" }], ["invalid_at", { invalid_at: "2026-11-09T09:00:00.000Z" }], + ["pre-1970", { due: "1969-12-31" }], + ["year-0", { due: "0000-01-01" }], ["missing", undefined], ] as const)("disarms on %s and re-arms when reopened", ([, overrides]) => Effect.gen(function* () { @@ -205,11 +209,69 @@ it.effect("keeps organizations apart", () => }).pipe(Effect.provide(layer)), ); -it.effect("refuses deferral card taps until the owner-tap dispatcher lands", () => +it.effect("syncs each head once, retries failures, and isolates failing items", () => + Effect.gen(function* () { + const { sql } = yield* setup(); + const hooks = yield* Memory.MemorySyncHooks; + const other = deferral({ id: KinMemoryItemId.make("def-2"), path: "deferrals/def-2.md" }); + const snapshot = ( + head: string, + items: ReadonlyArray, + duplicateIds: ReadonlyArray = [], + ) => ({ + head, + items: items.map((head) => ({ head, body: "" })), + duplicateIds: new Set(duplicateIds), + }); + const runs = () => + sql<{ itemId: string; state: string }>`SELECT item_id AS "itemId", state + FROM kin_deferral_runs WHERE org_id = ${orgId} ORDER BY item_id`; + yield* sql`CREATE TRIGGER fail_def_1 BEFORE INSERT ON kin_deferral_runs + WHEN NEW.item_id = 'def-1' BEGIN SELECT RAISE(ABORT, 'fixture'); END`; + yield* hooks.syncItems(orgId, snapshot("h1", [deferral(), other])); + assert.deepEqual(yield* runs(), [{ itemId: "def-2", state: "armed" }]); + + yield* sql`DROP TRIGGER fail_def_1`; + yield* hooks.syncItems(orgId, snapshot("h1", [deferral(), other])); + assert.deepEqual(yield* runs(), [ + { itemId: "def-1", state: "armed" }, + { itemId: "def-2", state: "armed" }, + ]); + yield* sql`UPDATE kin_deferral_runs SET state = 'disarmed' WHERE org_id = ${orgId} AND item_id = 'def-2'`; + yield* hooks.syncItems(orgId, snapshot("h1", [deferral(), other])); + assert.equal((yield* runs())[1]?.state, "disarmed"); + + const copy = deferral({ path: "deferrals/def-1-copy.md" }); + yield* hooks.syncItems(orgId, snapshot("h2", [deferral(), copy, other], ["def-1"])); + assert.deepEqual(yield* runs(), [ + { itemId: "def-1", state: "disarmed" }, + { itemId: "def-2", state: "armed" }, + ]); + assert.deepEqual( + (yield* triggers(orgId)).map(({ id, enabled }) => [id, enabled]), + [ + ["deferral:def-1:due", 0], + ["deferral:def-1:heads_up", 0], + ["deferral:def-2:due", 1], + ["deferral:def-2:heads_up", 1], + ], + ); + }).pipe(Effect.provide(layer)), +); + +it.effect("refuses deferral cards from the model and taps until the dispatcher lands", () => Effect.gen(function* () { const { service } = yield* setup(); yield* service.syncItem(deferral()); const chat = yield* Chat.KinChatService; + const [posted] = yield* card(orgId); + const upsert = yield* chat + .upsertWidget( + { _tag: "person", orgId, personId: KinPersonId.make(`owner-${orgId}`) }, + { chatId: KinChatId.make(`chat-${orgId}`), type: "deferral", state: posted!.state }, + ) + .pipe(Effect.flip); + assert.equal(upsert._tag === "KinChatError" && upsert.reason, "not_allowed"); const failure = yield* chat .act( { _tag: "person", orgId, personId: KinPersonId.make(`owner-${orgId}`) }, diff --git a/apps/server/src/kin/triggers/KinTriggerService.ts b/apps/server/src/kin/triggers/KinTriggerService.ts index 0d817b6bfe1a..d5f1041b8b88 100644 --- a/apps/server/src/kin/triggers/KinTriggerService.ts +++ b/apps/server/src/kin/triggers/KinTriggerService.ts @@ -64,6 +64,36 @@ const encodeSubject = Schema.encodeEffect(Schema.fromJsonString(KinTriggerSubjec const encodeSnapshot = Schema.encodeEffect(Schema.fromJsonString(DeferralSnapshot)); const iso = (ms: number) => DateTime.formatIso(DateTime.makeUnsafe(ms)); +interface StoredTrigger { + readonly runAt: number | undefined; + readonly enabled: boolean; + readonly nextRunAt: number | null; +} +interface Stored { + readonly run: { readonly state: string; readonly dueAt: number | null; readonly onDue: string }; + readonly triggers: Map; +} + +// A fired `once` keeps its runAt with next_run_at cleared; re-syncing must not refire it. +const triggerCurrent = (runAt: number | undefined, row: StoredTrigger | undefined) => + runAt === undefined + ? row === undefined || (!row.enabled && row.nextRunAt === null) + : row?.enabled === true && row.runAt === runAt; + +const isCurrent = (plan: DeferralPlan, stored: Stored | undefined) => + phases.every((phase) => + triggerCurrent( + plan.phases.find((entry) => entry.phase === phase)?.runAt, + stored?.triggers.get(phase), + ), + ) && + (plan.armed + ? stored !== undefined && + stored.run.state !== "disarmed" && + stored.run.dueAt === plan.dueAt && + stored.run.onDue === plan.onDue + : stored === undefined || stored.run.state === "disarmed"); + const make = Effect.gen(function* () { const sql = yield* SqlClient.SqlClient; const cache = yield* MemoryCache.MemoryCache; @@ -72,7 +102,53 @@ const make = Effect.gen(function* () { const publish = (event: Parameters[0]) => Option.isSome(hub) ? sql.afterCommit(hub.value.publish(event)) : Effect.void; - const syncTrigger = Effect.fn("KinTriggerService.syncTrigger")(function* ( + // Trigger rows are only written in the same transaction as their run row. + const readStored = Effect.fn("KinTriggerService.readStored")(function* ( + orgId: KinOrgId, + itemId?: KinMemoryItemId, + ) { + const rows = yield* sql<{ + itemId: string; + state: string; + dueAt: number | null; + onDue: string; + triggerId: string | null; + schedule: string | null; + enabled: number | null; + nextRunAt: number | null; + }>` + SELECT r.item_id AS "itemId", r.state, r.due_at AS "dueAt", r.on_due AS "onDue", + t.trigger_id AS "triggerId", t.schedule_json AS schedule, + t.enabled, t.next_run_at AS "nextRunAt" + FROM kin_deferral_runs r + LEFT JOIN kin_triggers t ON t.org_id = r.org_id + AND t.trigger_id IN ('deferral:' || r.item_id || ':heads_up', 'deferral:' || r.item_id || ':due') + WHERE r.org_id = ${orgId} ${itemId === undefined ? sql`` : sql`AND r.item_id = ${itemId}`} + ORDER BY r.item_id, t.trigger_id + `; + const stored = new Map(); + for (const row of rows) { + let entry = stored.get(row.itemId); + if (entry === undefined) { + entry = { + run: { state: row.state, dueAt: row.dueAt, onDue: row.onDue }, + triggers: new Map(), + }; + stored.set(row.itemId, entry); + } + const phase = phases.find((each) => deferralTriggerId(row.itemId, each) === row.triggerId); + if (phase === undefined || row.schedule === null) continue; + const schedule = yield* decodeSchedule(row.schedule); + entry.triggers.set(phase, { + runAt: schedule.type === "once" ? Date.parse(schedule.runAt) : undefined, + enabled: row.enabled === 1, + nextRunAt: row.nextRunAt, + }); + } + return stored; + }); + + const writeTrigger = Effect.fn("KinTriggerService.writeTrigger")(function* ( orgId: KinOrgId, itemId: KinMemoryItemId, phase: DeferralPhase, @@ -81,21 +157,9 @@ const make = Effect.gen(function* () { now: number, ) { const id = deferralTriggerId(itemId, phase); - const [row] = yield* sql<{ schedule: string; enabled: number; nextRunAt: number | null }>` - SELECT schedule_json AS schedule, enabled, next_run_at AS "nextRunAt" FROM kin_triggers - WHERE org_id = ${orgId} AND trigger_id = ${id} ORDER BY trigger_id - `; - if (runAt === undefined) { - if (row === undefined || (row.enabled === 0 && row.nextRunAt === null)) return false; - yield* sql`UPDATE kin_triggers SET enabled = 0, next_run_at = NULL, + if (runAt === undefined) + return yield* sql`UPDATE kin_triggers SET enabled = 0, next_run_at = NULL, updated_at = max(updated_at, ${now}) WHERE org_id = ${orgId} AND trigger_id = ${id}`; - return true; - } - if (row !== undefined && row.enabled === 1) { - const stored = yield* decodeSchedule(row.schedule); - // A fired `once` keeps its runAt with next_run_at cleared; re-syncing must not refire it. - if (stored.type === "once" && Date.parse(stored.runAt) === runAt) return false; - } const schedule = yield* encodeSchedule({ type: "once", runAt: iso(runAt) }); const subject = yield* encodeSubject({ type: "deferral", itemId, phase }); const inserted = yield* sql` @@ -109,7 +173,6 @@ const make = Effect.gen(function* () { time_zone = ${timeZone}, enabled = 1, next_run_at = ${runAt}, updated_at = max(updated_at, ${now}) WHERE org_id = ${orgId} AND trigger_id = ${id}`; - return true; }); const syncCard = Effect.fn("KinTriggerService.syncCard")(function* ( @@ -202,24 +265,21 @@ const make = Effect.gen(function* () { orgId: KinOrgId, itemId: KinMemoryItemId, item: SyncItem | undefined, + plan: DeferralPlan, + timeZone: string, + now: number, ) { - const plan = item === undefined ? disarmedPlan : planDeferral(item); - const timeZone = yield* cache.ownerTimeZone(orgId); - const now = yield* Clock.currentTimeMillis; return yield* sql.withTransaction( Effect.gen(function* () { const [org] = yield* sql`SELECT 1 FROM kin_orgs WHERE org_id = ${orgId} ORDER BY org_id`; if (org === undefined) return yield* Effect.fail("unknown_org" as const); - let changed = false; + const stored = (yield* readStored(orgId, itemId)).get(itemId); + if (isCurrent(plan, stored)) return "unchanged" as const; for (const phase of phases) { const runAt = plan.phases.find((entry) => entry.phase === phase)?.runAt; - if (yield* syncTrigger(orgId, itemId, phase, runAt, timeZone, now)) changed = true; + if (!triggerCurrent(runAt, stored?.triggers.get(phase))) + yield* writeTrigger(orgId, itemId, phase, runAt, timeZone, now); } - const [run] = yield* sql<{ state: string; dueAt: number | null; onDue: string }>` - SELECT state, due_at AS "dueAt", on_due AS "onDue" FROM kin_deferral_runs - WHERE org_id = ${orgId} AND item_id = ${itemId} ORDER BY item_id - `; - let result: SyncResult = "unchanged"; if (plan.armed && item !== undefined) { const snapshot = yield* encodeSnapshot(deferralSnapshot(item)); const inserted = yield* sql` @@ -227,25 +287,15 @@ const make = Effect.gen(function* () { VALUES (${orgId}, ${itemId}, 'armed', ${plan.dueAt}, ${plan.onDue}, ${snapshot}, ${now}) ON CONFLICT DO NOTHING RETURNING item_id `; - if (inserted.length === 1) result = "armed"; - else if ( - changed || - run?.state === "disarmed" || - run?.dueAt !== plan.dueAt || - run?.onDue !== plan.onDue - ) { + if (inserted.length === 0) yield* sql`UPDATE kin_deferral_runs SET state = 'armed', due_at = ${plan.dueAt}, on_due = ${plan.onDue}, snapshot_json = ${snapshot}, updated_at = ${now} WHERE org_id = ${orgId} AND item_id = ${itemId}`; - result = "armed"; - } - } else if (changed || (run !== undefined && run.state !== "disarmed")) { + } else yield* sql`UPDATE kin_deferral_runs SET state = 'disarmed', updated_at = ${now} WHERE org_id = ${orgId} AND item_id = ${itemId} AND state <> 'disarmed'`; - result = "disarmed"; - } - if (result !== "unchanged") yield* syncCard(orgId, itemId, item, plan, timeZone, now); - return result; + yield* syncCard(orgId, itemId, item, plan, timeZone, now); + return plan.armed ? ("armed" as const) : ("disarmed" as const); }), ); }); @@ -259,43 +309,74 @@ const make = Effect.gen(function* () { }), ); - const syncItem = Effect.fn("KinTriggerService.syncItem")(function* (item: SyncItem) { - if (item.kind !== "deferral") return "unchanged" as const; - return yield* apply(item.orgId, item.id, item).pipe(wrap(item.orgId)); - }); - return KinTriggerService.of({ - syncItem, + syncItem: Effect.fn("KinTriggerService.syncItem")(function* (item) { + if (item.kind !== "deferral") return "unchanged" as const; + const timeZone = yield* cache.ownerTimeZone(item.orgId); + const now = yield* Clock.currentTimeMillis; + return yield* apply(item.orgId, item.id, item, planDeferral(item), timeZone, now).pipe( + wrap(item.orgId), + ); + }), syncOrg: Effect.fn("KinTriggerService.syncOrg")(function* (orgId, items) { + const stored = yield* readStored(orgId).pipe(wrap(orgId)); const present = new Set(); + const pending: Array = []; for (const item of items) { if (item.orgId !== orgId || item.kind !== "deferral") continue; present.add(item.id); - yield* syncItem(item); + const plan = planDeferral(item); + if (!isCurrent(plan, stored.get(item.id))) pending.push([item.id, item, plan]); } - const runs = yield* sql<{ itemId: KinMemoryItemId }>` - SELECT item_id AS "itemId" FROM kin_deferral_runs - WHERE org_id = ${orgId} AND state <> 'disarmed' ORDER BY item_id - `.pipe(wrap(orgId)); - for (const run of runs) - if (!present.has(run.itemId)) yield* apply(orgId, run.itemId, undefined).pipe(wrap(orgId)); + for (const [itemId, entry] of stored) + if (!present.has(itemId) && entry.run.state !== "disarmed") + pending.push([KinMemoryItemId.make(itemId), undefined, disarmedPlan]); + if (pending.length === 0) return; + const timeZone = yield* cache.ownerTimeZone(orgId); + const now = yield* Clock.currentTimeMillis; + const failures: Array = []; + for (const [itemId, item, plan] of pending) + yield* apply(orgId, itemId, item, plan, timeZone, now).pipe( + wrap(orgId), + Effect.catch((error) => { + failures.push(error); + return Effect.logWarning("Could not sync deferral", { orgId, itemId, cause: error }); + }), + ); + if (failures.length > 0) return yield* failures[0]!; }), }); }); export const layer = Layer.effect(KinTriggerService, make).pipe(Layer.provide(MemoryCache.layer)); -/** Feeds each front-matter cache snapshot into deferral arming. */ +/** Arms deferrals from each new memory head; a failed sync retries on the next load. */ export const syncHooksLayer = Layer.effect( Memory.MemorySyncHooks, Effect.gen(function* () { const service = yield* KinTriggerService; - return Memory.MemorySyncHooks.of({ - syncItems: Effect.fn("KinTriggerService.syncItems")(function* (orgId, items) { + const syncedHeads = new Map(); + return { + syncItems: Effect.fn("KinTriggerService.syncItems")(function* (orgId, snapshot) { + if (syncedHeads.get(orgId) === snapshot.head) return; yield* service - .syncOrg(orgId, items) - .pipe(Effect.mapError((cause) => new Memory.MemorySyncHookError({ orgId, cause }))); + .syncOrg( + orgId, + snapshot.items.map(({ head }) => ({ + ...head, + duplicate: snapshot.duplicateIds.has(head.id), + })), + ) + .pipe( + Effect.tap(() => Effect.sync(() => syncedHeads.set(orgId, snapshot.head))), + Effect.catch((error) => + Effect.logWarning("Could not sync deferral triggers; retrying on next load", { + orgId, + cause: error, + }), + ), + ); }), - }); + }; }), ); diff --git a/apps/server/src/kin/triggers/deferrals.test.ts b/apps/server/src/kin/triggers/deferrals.test.ts index 7bc6103ec78c..706d45c58f43 100644 --- a/apps/server/src/kin/triggers/deferrals.test.ts +++ b/apps/server/src/kin/triggers/deferrals.test.ts @@ -12,6 +12,7 @@ import { } from "@t3tools/contracts"; import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; import * as Schema from "effect/Schema"; import * as SqlClient from "effect/sql/SqlClient"; import * as TestClock from "effect/testing/TestClock"; @@ -47,7 +48,11 @@ it.effect("applies verified owner taps on the confirm card and ignores forged on const writer = Layer.mock(MemoryWriter.MemoryWriter)({ stage: (_org, _wakeup, change) => Effect.sync(() => void staged.push(change)), }); - const tapOnce = Effect.fn("test.deferralTap")(function* (actionId: string, label: string) { + const tapOnce = Effect.fn("test.deferralTap")(function* ( + actionId: string, + label: string, + target: KinWidgetId = widgetId, + ) { const memberId = "owner-member-a"; // Stands in for the gated dispatcher: chat act refuses deferral taps today. const message = yield* repo.insertMessage({ @@ -60,11 +65,11 @@ it.effect("applies verified owner taps on the confirm card and ignores forged on memberId: KinMemberId.make(memberId), }, kind: "widget_action", - body: encodeJson({ widgetId, revision: 1, actionId, value: "def-1" }), + body: encodeJson({ widgetId: target, revision: 1, actionId, value: "def-1" }), intent: null, mentions: [], - replyTo: KinMessageId.make(widgetId), - widgetId, + replyTo: KinMessageId.make(target), + widgetId: target, floorRunId: null, status: "posted", sentBy: KinPersonId.make("owner-a"), @@ -102,7 +107,8 @@ it.effect("applies verified owner taps on the confirm card and ignores forged on yield* queue.finish({ orgId, wakeupId, status: "completed" }); return result; }); - const tap = (actionId: string, label: string) => Effect.scoped(tapOnce(actionId, label)); + const tap = (actionId: string, label: string, target?: KinWidgetId) => + Effect.scoped(tapOnce(actionId, label, target)); const remind = yield* tap("remind", "owner"); assert.equal(remind._tag === "Success" && remind.success.action, "remind"); @@ -114,6 +120,44 @@ it.effect("applies verified owner taps on the confirm card and ignores forged on assert.equal(change._tag === "Success" && change.success.action, "change"); assert.lengthOf(staged, 1); + const real = Option.getOrThrow(yield* repo.getWidget({ orgId, widgetId })); + const forgedId = KinWidgetId.make("model-card"); + const anchor = yield* repo.insertMessage({ + orgId, + chatId: real.chatId, + messageId: KinMessageId.make(forgedId), + author: { _tag: "system" }, + kind: "system", + body: "", + intent: null, + mentions: [], + replyTo: null, + widgetId: null, + floorRunId: null, + status: "posted", + sentBy: null, + clientMessageId: null, + createdAt: "2026-11-09T09:00:00.000Z", + editedAt: null, + }); + yield* repo.insertWidget({ + orgId, + chatId: real.chatId, + messageId: anchor.messageId, + widgetId: forgedId, + widgetClass: "native", + type: "deferral", + state: real.state, + source: null, + feed: null, + awaiting: [], + pinnedAt: null, + closedAt: null, + updatedAt: "2026-11-09T09:00:00.000Z", + }); + assert.equal((yield* tap("remind", "forged", forgedId))._tag, "Failure"); + assert.lengthOf(staged, 1); + const member = yield* tap("remind", "demoted"); assert.equal(member._tag, "Failure"); assert.lengthOf(staged, 1); diff --git a/apps/server/src/kin/triggers/deferrals.ts b/apps/server/src/kin/triggers/deferrals.ts index 829fb11db2c2..a90798dab3ef 100644 --- a/apps/server/src/kin/triggers/deferrals.ts +++ b/apps/server/src/kin/triggers/deferrals.ts @@ -36,7 +36,8 @@ export const deferralTriggerId = (itemId: string, phase: DeferralPhase) => KinTriggerId.make(`deferral:${itemId}:${phase}`); export const deferralWidgetId = (orgId: string, itemId: string) => `deferral:${orgId}:${itemId}`; -// A deferral without on_due only reminds: silence never starts work. +// A deferral without on_due only reminds: silence never starts work. Pre-epoch run +// times would fail every scheduler tick, so they leave the item unarmed. export function planDeferral( item: MemoryItemHead & { readonly duplicate?: boolean }, ): DeferralPlan { @@ -52,13 +53,10 @@ export function planDeferral( dueAt !== null; if (!armed || dueAt === null) return { armed: false, dueAt, onDue, phases: [] }; const dueFire = { phase: "due" as const, runAt: dueAt }; - return { - armed, - dueAt, - onDue, - phases: - onDue === "start" ? [{ phase: "heads_up", runAt: dueAt - HEADS_UP_MS }, dueFire] : [dueFire], - }; + const phases: DeferralPlan["phases"] = + onDue === "start" ? [{ phase: "heads_up", runAt: dueAt - HEADS_UP_MS }, dueFire] : [dueFire]; + if (phases.some(({ runAt }) => runAt < 0)) return { armed: false, dueAt, onDue, phases: [] }; + return { armed, dueAt, onDue, phases }; } /** The item half of the recheck baseline; TRIG-8 adds the GitHub half. */ @@ -141,7 +139,11 @@ const make = Effect.gen(function* () { ); const action = yield* decodeAction(tap.action); const card = yield* decodeCard(tap.widget.state); - if (card.itemId !== action.value) return yield* Effect.fail("unknown_item" as const); + if ( + card.itemId !== action.value || + tap.widget.widgetId !== deferralWidgetId(orgId, card.itemId) + ) + return yield* Effect.fail("unknown_item" as const); if (action.actionId === "remind") { const item = yield* memory.readItemQuietly(orgId, card.itemId); if (item.head.kind !== "deferral" || item.head.status !== "open") diff --git a/docs/kin/specs/triggers.md b/docs/kin/specs/triggers.md index 852d9f095ebb..d3ee752d8c05 100644 --- a/docs/kin/specs/triggers.md +++ b/docs/kin/specs/triggers.md @@ -113,7 +113,7 @@ Defaults: brief 08:30 daily, summary 18:30 Mon–Fri, dream 03:00 daily, full re | Kind | Late policy (decided by the consumer, using `lateByMs` and owner time) | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Deferral `heads_up` | If `due` has also passed, skip the heads-up and handle `due` as late. | -| Deferral `due` | Run the due flow with "This was due at 9:00"; the grace starts from now. | +| Deferral `due` | Within the 30-minute grace, run the due flow with "This was due at 9:00"; the grace starts from now. Older fires ask, never start. | | Reminder, follow-up | Deliver with "This was due at …". Pings respect quiet hours. | | Morning brief | Post if before the evening summary time; otherwise fold into the evening summary. | | Evening summary | Post if before the next dream; otherwise fold into the next morning brief. | @@ -205,7 +205,7 @@ Arming comes from memory. When the front-matter cache (LEAD) sees a `deferrals/* Item edits move or disarm the triggers: a new `due` re-arms; `status` other than `open` or a set `invalid_at` disables them. A due time already past at save fires at once, marked late; no "pick a future time" error. A missing `on_due` means `remind`, so silence never starts work. -The cache hook is `MemorySyncHooks` in [`Memory.ts`](../../../apps/server/src/kin/memory/Memory.ts): every newly loaded snapshot goes to `KinTriggerService.syncOrg`, which also disarms armed deferrals missing from the snapshot or sharing a duplicate id. A failed sync retries on the next load, and `trigger_reconcile` remains the backstop. A commit to the default branch moves the cache to the new head and reloads it, so a `kin_defer` item arms when its wake-up commits, not at the next wake-up; shadow (L0) commits never arm. Trigger ids are `deferral::heads_up|due`. Re-syncing an unchanged `due` writes nothing, so a fired `once` is never re-armed. The run row in `kin_deferral_runs` (provisional migration K017) holds the snapshot and an `armed`/`disarmed` state; TRIG-8 owns the due-flow states. The snapshot holds the item half only (`recorded_at`, `superseded_by`, links). There is no GitHub reader in Kin yet, so TRIG-8 must add the GitHub half (issue/PR state, assignees, linked PRs) at arm time before the due flow ships. +The cache hook is `MemorySyncHooks` in [`Memory.ts`](../../../apps/server/src/kin/memory/Memory.ts): each new head goes once to `KinTriggerService.syncOrg`, which also disarms armed deferrals missing from the snapshot or sharing a duplicate id. A failing item is logged without blocking the others, the head retries on the next load, and `trigger_reconcile` remains the backstop. A due time whose fires would land before 1970 never arms; `kin_defer` accepts only years 2000–2099. A commit to the default branch moves the cache to the new head and reloads it, so a `kin_defer` item arms when its wake-up commits, not at the next wake-up; shadow (L0) commits never arm. Trigger ids are `deferral::heads_up|due`. Re-syncing an unchanged `due` writes nothing, so a fired `once` is never re-armed. The run row in `kin_deferral_runs` (provisional migration K017) holds the snapshot and an `armed`/`disarmed` state; TRIG-8 owns the due-flow states. The snapshot holds the item half only (`recorded_at`, `superseded_by`, links). There is no GitHub reader in Kin yet, so TRIG-8 must add the GitHub half (issue/PR state, assignees, linked PRs) at arm time before the due flow ships. **Confirm.** When the lead calls `kin_defer` (LEAD), Kin writes the item, arms the triggers, and the lead posts a `KinDeferralCard` widget (CHAT envelope): "Deferred to Fri 13 Nov, 9:00. I'll start then." [Change] [Just remind me]. [Just remind me] sets `on_due: remind`, and the triggers re-arm. [Change] writes nothing: it hands the item to the lead, which asks the owner what to change, marks the old item `cancelled` and calls `kin_defer` for the new one. @@ -234,7 +234,8 @@ armed ──heads_up fire──▶ recheck ──changed──▶ asked (decis ``` - **The recheck is code.** It runs `gh api` reads for every GitHub link plus a read of the memory item. Any difference from the snapshot means "changed": an issue closed, an assignee added, another linked PR, or the item superseded. The ask then names what changed. -- **Late.** If the machine woke after `due`, the `heads_up` fire is skipped. The `due` fire posts the same card with "This was due at 9:00" and a 30-minute grace from now; silence still means go. +- **Late.** If the machine woke after `due`, the `heads_up` fire is skipped. A `due` fire within the 30-minute grace window posts the same card with "This was due at 9:00" and a grace from now; silence still means go. An older fire asks instead of starting. +- **Stale fires.** Fires wait in the inbox until TRIG-8 consumes them. TRIG-8 drops a fire whose run row is `disarmed` or whose `due_at` no longer equals the fire's due instant. - **Level and stop switch.** Below L2, or with the org's stop switch on, `start` becomes `ask`. Silence never starts work then. - **Idempotent start.** Starting is a Work-class action keyed by `fireId`, so a replay can't start two workers. - **Bring it up early.** When a message touches the topic before the due time, the lead mentions it (LEAD, using the cache). The Monday morning brief lists deferrals due this week. @@ -512,7 +513,7 @@ Kin runs on one always-on machine, the **Kin host**. The laptop and phone are cl - **Scheduler:** a deferral due 09:00 +05:30 fires once at 09:00. Two ticks at the same instant give one inbox row. Advancing the clock 10 h with the scheduler stopped, then starting it, gives one inbox fire with `lateByMs = 10 h`; the deferral consumer (TRIG-8) posts the "This was due at 9:00" card. Recurring downtime emits one stored slot, not every missed occurrence. - **Timezone:** with the server zone `UTC` and the org zone `Asia/Kolkata`, the dream fires at 21:30 UTC. A 09:00 routine in `America/New_York` stays at 09:00 across both DST transitions; weekdays are owner-local. Two orgs with different zones fire independently; changing one org's zone or routine times recomputes only its schedules. - **Sink:** a signed GitHub `pull_request` request through the real `ScheduledTaskService` gives exactly one inbox row and no thread launch. A replay gives `duplicate` and no new row. A bot-sender request gives `filtered`. A non-Kin task still launches normally. -- **Deferral:** unchanged recheck, then heads-up, then silence, then `started` at due. A linked issue closed before due leads to `asked`, and nothing starts. With the stop switch on, it asks. [Monday] re-arms to next Monday 09:00. +- **Deferral:** unchanged recheck, then heads-up, then silence, then `started` at due. A linked issue closed before due leads to `asked`, and nothing starts. With the stop switch on, it asks. [Monday] re-arms to next Monday 09:00. A `due` fire consumed two hours late asks; a queued fire for a disarmed or moved deferral is dropped. - **Dream:** a dream touching `rules.md` fails, and `main` is unchanged. A dream with one journal fold and one `decisions/` change opens two PRs, and only the auto one merges. - **Secret scan:** a journal line holding `ghp_` plus 36 characters blocks the entire commit, and the owner gets one typed notification without the value. - **Purge:** on a fixture repo, the file is gone from `git log --all -p`, a tombstone exists, and an audit row exists. diff --git a/packages/contracts/src/kinLead.ts b/packages/contracts/src/kinLead.ts index 1c7c00c6d2ac..c3594ec11f9d 100644 --- a/packages/contracts/src/kinLead.ts +++ b/packages/contracts/src/kinLead.ts @@ -214,7 +214,7 @@ export const KinEvent = Schema.Union([ Schema.Array( Schema.Struct({ routine: KinLeadRoutine, - dueAt: Schema.toEncoded(CanonicalUtcTimestamp), + dueAt: CanonicalUtcTimestamp, }), ), ), From bcb082fa0e8ebd1f4368893237c879ac6bd882a0 Mon Sep 17 00:00:00 2001 From: GLDRoger <130458023+GLDRoger@users.noreply.github.com> Date: Sun, 8 Nov 2026 19:29:06 +0530 Subject: [PATCH 3/4] fix(kin): pin on_due re-arm, isolate bad trigger rows, cap sync retries Co-Authored-By: Claude Opus 5.5 --- .../kin/triggers/KinTriggerService.test.ts | 36 +++++++++++++++++++ .../src/kin/triggers/KinTriggerService.ts | 36 ++++++++++++++----- docs/kin/specs/triggers.md | 2 +- 3 files changed, 65 insertions(+), 9 deletions(-) diff --git a/apps/server/src/kin/triggers/KinTriggerService.test.ts b/apps/server/src/kin/triggers/KinTriggerService.test.ts index 6e77c48b96ce..07fe4e79dee0 100644 --- a/apps/server/src/kin/triggers/KinTriggerService.test.ts +++ b/apps/server/src/kin/triggers/KinTriggerService.test.ts @@ -130,6 +130,24 @@ it.effect("arms from front matter, re-arms on edits, and re-syncs without writes SELECT state, due_at AS "dueAt", on_due AS "onDue" FROM kin_deferral_runs WHERE org_id = ${orgId} ORDER BY item_id`; assert.deepEqual(run, { state: "armed", dueAt: Date.parse(moved), onDue: "remind" }); + + // Same fires, different on_due: only the run row and card can tell them apart. + assert.equal(yield* service.syncItem(deferral({ due: moved, on_due: "ask" })), "armed"); + const [asked] = yield* sql<{ onDue: string }>`SELECT on_due AS "onDue" FROM kin_deferral_runs + WHERE org_id = ${orgId} ORDER BY item_id`; + assert.equal(asked?.onDue, "ask"); + assert.equal((yield* card(orgId))[0]?.state.onDue, "ask"); + + yield* sql`UPDATE kin_triggers SET schedule_json = 'not json' + WHERE org_id = ${orgId} AND trigger_id = 'deferral:def-1:due'`; + assert.equal(yield* service.syncItem(deferral({ due: moved, on_due: "ask" })), "armed"); + assert.deepEqual( + (yield* triggers(orgId)).map(({ enabled, nextRunAt }) => [enabled, nextRunAt]), + [ + [1, Date.parse(moved)], + [0, null], + ], + ); }).pipe(Effect.provide(layer)), ); @@ -256,6 +274,24 @@ it.effect("syncs each head once, retries failures, and isolates failing items", ["deferral:def-2:heads_up", 1], ], ); + + const stuck = deferral({ id: KinMemoryItemId.make("def-3"), path: "deferrals/def-3.md" }); + yield* sql`CREATE TRIGGER fail_def_3 BEFORE INSERT ON kin_deferral_runs + WHEN NEW.item_id = 'def-3' BEGIN SELECT RAISE(ABORT, 'fixture'); END`; + for (let attempt = 0; attempt < 3; attempt++) + yield* hooks.syncItems(orgId, snapshot("h3", [stuck, other])); + yield* sql`DROP TRIGGER fail_def_3`; + yield* hooks.syncItems(orgId, snapshot("h3", [stuck, other])); + assert.notInclude( + (yield* runs()).map(({ itemId }) => itemId), + "def-3", + "a head that failed three times is not retried", + ); + yield* hooks.syncItems(orgId, snapshot("h4", [stuck, other])); + assert.include( + (yield* runs()).map(({ itemId }) => itemId), + "def-3", + ); }).pipe(Effect.provide(layer)), ); diff --git a/apps/server/src/kin/triggers/KinTriggerService.ts b/apps/server/src/kin/triggers/KinTriggerService.ts index d5f1041b8b88..0a2c2949591c 100644 --- a/apps/server/src/kin/triggers/KinTriggerService.ts +++ b/apps/server/src/kin/triggers/KinTriggerService.ts @@ -138,9 +138,13 @@ const make = Effect.gen(function* () { } const phase = phases.find((each) => deferralTriggerId(row.itemId, each) === row.triggerId); if (phase === undefined || row.schedule === null) continue; - const schedule = yield* decodeSchedule(row.schedule); + // An undecodable row reads as stale, so the next apply overwrites it instead of failing the org. + const schedule = yield* decodeSchedule(row.schedule).pipe(Effect.option); entry.triggers.set(phase, { - runAt: schedule.type === "once" ? Date.parse(schedule.runAt) : undefined, + runAt: + Option.isSome(schedule) && schedule.value.type === "once" + ? Date.parse(schedule.value.runAt) + : Number.NaN, enabled: row.enabled === 1, nextRunAt: row.nextRunAt, }); @@ -350,15 +354,20 @@ const make = Effect.gen(function* () { export const layer = Layer.effect(KinTriggerService, make).pipe(Layer.provide(MemoryCache.layer)); -/** Arms deferrals from each new memory head; a failed sync retries on the next load. */ +const maxSyncAttempts = 3; + +/** Arms deferrals from each new memory head; a failed sync retries on the next few loads. */ export const syncHooksLayer = Layer.effect( Memory.MemorySyncHooks, Effect.gen(function* () { const service = yield* KinTriggerService; const syncedHeads = new Map(); + const failedAttempts = new Map(); return { syncItems: Effect.fn("KinTriggerService.syncItems")(function* (orgId, snapshot) { if (syncedHeads.get(orgId) === snapshot.head) return; + const failed = failedAttempts.get(orgId); + const attempt = failed?.head === snapshot.head ? failed.count + 1 : 1; yield* service .syncOrg( orgId, @@ -368,13 +377,24 @@ export const syncHooksLayer = Layer.effect( })), ) .pipe( - Effect.tap(() => Effect.sync(() => syncedHeads.set(orgId, snapshot.head))), - Effect.catch((error) => - Effect.logWarning("Could not sync deferral triggers; retrying on next load", { - orgId, - cause: error, + Effect.tap(() => + Effect.sync(() => { + syncedHeads.set(orgId, snapshot.head); + failedAttempts.delete(orgId); }), ), + Effect.catch((error) => { + // A permanent failure would otherwise rerun the sync inside the memory lock on every load. + const giveUp = attempt >= maxSyncAttempts; + if (giveUp) syncedHeads.set(orgId, snapshot.head); + else failedAttempts.set(orgId, { head: snapshot.head, count: attempt }); + return Effect.logWarning( + giveUp + ? "Could not sync deferral triggers; skipping this head" + : "Could not sync deferral triggers; retrying on next load", + { orgId, attempt, cause: error }, + ); + }), ); }), }; diff --git a/docs/kin/specs/triggers.md b/docs/kin/specs/triggers.md index d3ee752d8c05..c21cf731d6d0 100644 --- a/docs/kin/specs/triggers.md +++ b/docs/kin/specs/triggers.md @@ -205,7 +205,7 @@ Arming comes from memory. When the front-matter cache (LEAD) sees a `deferrals/* Item edits move or disarm the triggers: a new `due` re-arms; `status` other than `open` or a set `invalid_at` disables them. A due time already past at save fires at once, marked late; no "pick a future time" error. A missing `on_due` means `remind`, so silence never starts work. -The cache hook is `MemorySyncHooks` in [`Memory.ts`](../../../apps/server/src/kin/memory/Memory.ts): each new head goes once to `KinTriggerService.syncOrg`, which also disarms armed deferrals missing from the snapshot or sharing a duplicate id. A failing item is logged without blocking the others, the head retries on the next load, and `trigger_reconcile` remains the backstop. A due time whose fires would land before 1970 never arms; `kin_defer` accepts only years 2000–2099. A commit to the default branch moves the cache to the new head and reloads it, so a `kin_defer` item arms when its wake-up commits, not at the next wake-up; shadow (L0) commits never arm. Trigger ids are `deferral::heads_up|due`. Re-syncing an unchanged `due` writes nothing, so a fired `once` is never re-armed. The run row in `kin_deferral_runs` (provisional migration K017) holds the snapshot and an `armed`/`disarmed` state; TRIG-8 owns the due-flow states. The snapshot holds the item half only (`recorded_at`, `superseded_by`, links). There is no GitHub reader in Kin yet, so TRIG-8 must add the GitHub half (issue/PR state, assignees, linked PRs) at arm time before the due flow ships. +The cache hook is `MemorySyncHooks` in [`Memory.ts`](../../../apps/server/src/kin/memory/Memory.ts): each new head goes once to `KinTriggerService.syncOrg`, which also disarms armed deferrals missing from the snapshot or sharing a duplicate id. A failing item is logged without blocking the others, and the head retries on the next two loads, then waits for the next head. The deferral `trigger_reconcile` described below is not built yet, so until it is, a new head is the only recovery. A due time whose fires would land before 1970 never arms; `kin_defer` accepts only years 2000–2099. A commit to the default branch moves the cache to the new head and reloads it, so a `kin_defer` item arms when its wake-up commits, not at the next wake-up; shadow (L0) commits never arm. Trigger ids are `deferral::heads_up|due`. Re-syncing an unchanged `due` writes nothing, so a fired `once` is never re-armed. The run row in `kin_deferral_runs` (provisional migration K017) holds the snapshot and an `armed`/`disarmed` state; TRIG-8 owns the due-flow states. The snapshot holds the item half only (`recorded_at`, `superseded_by`, links). There is no GitHub reader in Kin yet, so TRIG-8 must add the GitHub half (issue/PR state, assignees, linked PRs) at arm time before the due flow ships. **Confirm.** When the lead calls `kin_defer` (LEAD), Kin writes the item, arms the triggers, and the lead posts a `KinDeferralCard` widget (CHAT envelope): "Deferred to Fri 13 Nov, 9:00. I'll start then." [Change] [Just remind me]. [Just remind me] sets `on_due: remind`, and the triggers re-arm. [Change] writes nothing: it hands the item to the lead, which asks the owner what to change, marks the old item `cancelled` and calls `kin_defer` for the new one. From fdb0631fd9b9746d7eeecf4ecb4056ed666c3100 Mon Sep 17 00:00:00 2001 From: GLDRoger <130458023+GLDRoger@users.noreply.github.com> Date: Sun, 8 Nov 2026 19:30:11 +0530 Subject: [PATCH 4/4] chore(kin): take migration K016 for deferral runs Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/persistence/KinMigrations.test.ts | 10 +++++----- apps/server/src/kin/persistence/KinMigrations.ts | 5 ++--- .../{K017_DeferralRuns.ts => K016_DeferralRuns.ts} | 0 docs/kin/specs/triggers.md | 2 +- 4 files changed, 8 insertions(+), 9 deletions(-) rename apps/server/src/kin/persistence/migrations/{K017_DeferralRuns.ts => K016_DeferralRuns.ts} (100%) diff --git a/apps/server/src/kin/persistence/KinMigrations.test.ts b/apps/server/src/kin/persistence/KinMigrations.test.ts index 1e301dddb8cf..0877625fa90a 100644 --- a/apps/server/src/kin/persistence/KinMigrations.test.ts +++ b/apps/server/src/kin/persistence/KinMigrations.test.ts @@ -109,7 +109,7 @@ describe("Kin migrations", () => { { migration_id: 13, name: "Routines" }, { migration_id: 14, name: "LeadToolCalls" }, { migration_id: 15, name: "AuthSessionKeys" }, - { migration_id: 17, name: "DeferralRuns" }, + { migration_id: 16, name: "DeferralRuns" }, ]); assert.deepStrictEqual( upstreamBefore.map((row) => [row.migration_id, row.name] as const), @@ -171,7 +171,7 @@ describe("Kin migrations", () => { { migration_id: 13, name: "Routines" }, { migration_id: 14, name: "LeadToolCalls" }, { migration_id: 15, name: "AuthSessionKeys" }, - { migration_id: 17, name: "DeferralRuns" }, + { migration_id: 16, name: "DeferralRuns" }, ]); assert.deepStrictEqual(yield* upstreamHistory, upstreamBefore); assert.deepStrictEqual(yield* sql`SELECT * FROM kin_orgs`, [ @@ -258,7 +258,7 @@ describe("Kin migrations", () => { [13, "Routines"], [14, "LeadToolCalls"], [15, "AuthSessionKeys"], - [17, "DeferralRuns"], + [16, "DeferralRuns"], ]); const before = yield* kinSchema; assert.deepStrictEqual( @@ -322,7 +322,7 @@ describe("Kin migrations", () => { [13, "Routines"], [14, "LeadToolCalls"], [15, "AuthSessionKeys"], - [17, "DeferralRuns"], + [16, "DeferralRuns"], ]); assert.deepStrictEqual( yield* sql`SELECT member_id FROM kin_chat_members WHERE org_id = 'org' ORDER BY member_id`, @@ -363,7 +363,7 @@ describe("Kin migrations", () => { { migration_id: 13, name: "Routines" }, { migration_id: 14, name: "LeadToolCalls" }, { migration_id: 15, name: "AuthSessionKeys" }, - { migration_id: 17, name: "DeferralRuns" }, + { migration_id: 16, name: "DeferralRuns" }, ]); assert.deepStrictEqual(yield* runKinMigrations(), []); assert.deepStrictEqual(yield* runMigrations(), []); diff --git a/apps/server/src/kin/persistence/KinMigrations.ts b/apps/server/src/kin/persistence/KinMigrations.ts index daacd35bb652..f93768bc7945 100644 --- a/apps/server/src/kin/persistence/KinMigrations.ts +++ b/apps/server/src/kin/persistence/KinMigrations.ts @@ -18,8 +18,7 @@ import SecretAllow from "./migrations/K012_SecretAllow.ts"; import Routines from "./migrations/K013_Routines.ts"; import LeadToolCalls from "./migrations/K014_LeadToolCalls.ts"; import AuthSessionKeys from "./migrations/K015_AuthSessionKeys.ts"; -// Provisional number; renumbered at merge. -import DeferralRuns from "./migrations/K017_DeferralRuns.ts"; +import DeferralRuns from "./migrations/K016_DeferralRuns.ts"; const run = Migrator.make({}); const loader = Migrator.fromRecord({ @@ -38,7 +37,7 @@ const loader = Migrator.fromRecord({ "13_Routines": Routines, "14_LeadToolCalls": LeadToolCalls, "15_AuthSessionKeys": AuthSessionKeys, - "17_DeferralRuns": DeferralRuns, + "16_DeferralRuns": DeferralRuns, }); export const runKinMigrations = Effect.fn("KinMigrations.run")(function* () { diff --git a/apps/server/src/kin/persistence/migrations/K017_DeferralRuns.ts b/apps/server/src/kin/persistence/migrations/K016_DeferralRuns.ts similarity index 100% rename from apps/server/src/kin/persistence/migrations/K017_DeferralRuns.ts rename to apps/server/src/kin/persistence/migrations/K016_DeferralRuns.ts diff --git a/docs/kin/specs/triggers.md b/docs/kin/specs/triggers.md index c21cf731d6d0..4ff8bdfa6229 100644 --- a/docs/kin/specs/triggers.md +++ b/docs/kin/specs/triggers.md @@ -205,7 +205,7 @@ Arming comes from memory. When the front-matter cache (LEAD) sees a `deferrals/* Item edits move or disarm the triggers: a new `due` re-arms; `status` other than `open` or a set `invalid_at` disables them. A due time already past at save fires at once, marked late; no "pick a future time" error. A missing `on_due` means `remind`, so silence never starts work. -The cache hook is `MemorySyncHooks` in [`Memory.ts`](../../../apps/server/src/kin/memory/Memory.ts): each new head goes once to `KinTriggerService.syncOrg`, which also disarms armed deferrals missing from the snapshot or sharing a duplicate id. A failing item is logged without blocking the others, and the head retries on the next two loads, then waits for the next head. The deferral `trigger_reconcile` described below is not built yet, so until it is, a new head is the only recovery. A due time whose fires would land before 1970 never arms; `kin_defer` accepts only years 2000–2099. A commit to the default branch moves the cache to the new head and reloads it, so a `kin_defer` item arms when its wake-up commits, not at the next wake-up; shadow (L0) commits never arm. Trigger ids are `deferral::heads_up|due`. Re-syncing an unchanged `due` writes nothing, so a fired `once` is never re-armed. The run row in `kin_deferral_runs` (provisional migration K017) holds the snapshot and an `armed`/`disarmed` state; TRIG-8 owns the due-flow states. The snapshot holds the item half only (`recorded_at`, `superseded_by`, links). There is no GitHub reader in Kin yet, so TRIG-8 must add the GitHub half (issue/PR state, assignees, linked PRs) at arm time before the due flow ships. +The cache hook is `MemorySyncHooks` in [`Memory.ts`](../../../apps/server/src/kin/memory/Memory.ts): each new head goes once to `KinTriggerService.syncOrg`, which also disarms armed deferrals missing from the snapshot or sharing a duplicate id. A failing item is logged without blocking the others, and the head retries on the next two loads, then waits for the next head. The deferral `trigger_reconcile` described below is not built yet, so until it is, a new head is the only recovery. A due time whose fires would land before 1970 never arms; `kin_defer` accepts only years 2000–2099. A commit to the default branch moves the cache to the new head and reloads it, so a `kin_defer` item arms when its wake-up commits, not at the next wake-up; shadow (L0) commits never arm. Trigger ids are `deferral::heads_up|due`. Re-syncing an unchanged `due` writes nothing, so a fired `once` is never re-armed. The run row in `kin_deferral_runs` (migration K016) holds the snapshot and an `armed`/`disarmed` state; TRIG-8 owns the due-flow states. The snapshot holds the item half only (`recorded_at`, `superseded_by`, links). There is no GitHub reader in Kin yet, so TRIG-8 must add the GitHub half (issue/PR state, assignees, linked PRs) at arm time before the due flow ships. **Confirm.** When the lead calls `kin_defer` (LEAD), Kin writes the item, arms the triggers, and the lead posts a `KinDeferralCard` widget (CHAT envelope): "Deferred to Fri 13 Nov, 9:00. I'll start then." [Change] [Just remind me]. [Just remind me] sets `on_due: remind`, and the triggers re-arm. [Change] writes nothing: it hands the item to the lead, which asks the owner what to change, marks the old item `cancelled` and calls `kin_defer` for the new one.