Compare commits
1 Commits
feat/a4-mo
...
feat/a1-no
| Author | SHA1 | Date | |
|---|---|---|---|
|
cd80ca1025 |
@@ -1,138 +0,0 @@
|
||||
# Fleet Backlog Conventions
|
||||
|
||||
The **backlog** is Mosaic's native backlog-of-record for fleet work. It is built
|
||||
end-to-end on Mosaic's own storage layer (`@mosaicstack/db`, drizzle/Postgres)
|
||||
and surfaced as `mosaic fleet backlog <sub> --json`.
|
||||
|
||||
> **Mosaic-native, no Hermes.** This backlog REPLACES the former Hermes adapter.
|
||||
> There is **no** runtime dependency on Hermes, `hermes kanban`, or `~/.hermes`
|
||||
> anywhere in this feature. Anything previously delegated to Hermes is recreated
|
||||
> here on Mosaic's own Postgres storage layer.
|
||||
|
||||
## Storage tier — PGlite by default, Postgres by config
|
||||
|
||||
The backlog uses the existing Mosaic storage layer; there is **no** new database
|
||||
engine (no sqlite, no raw client).
|
||||
|
||||
| Condition | Tier | Data location |
|
||||
| ------------------------------ | -------------------- | -------------------------------- |
|
||||
| `DATABASE_URL` set | Full server Postgres | the configured database |
|
||||
| `PGLITE_DATA_DIR` set (no URL) | Embedded PGlite | that directory |
|
||||
| neither (default) | Embedded PGlite | `~/.config/mosaic/fleet/backlog` |
|
||||
|
||||
PGlite is real Postgres semantics in-process — including the row locks the atomic
|
||||
claim relies on — so the **same code** runs on a laptop (embedded, single-host
|
||||
default) and on a full Postgres deployment. Switching tiers is config-only.
|
||||
|
||||
The schema (`backlog` table) is created automatically on first CLI use:
|
||||
`runMigrations()` for Postgres, `runPgliteMigrations()` for embedded PGlite.
|
||||
|
||||
### Update safety
|
||||
|
||||
The embedded PGlite store lives under `~/.config/mosaic/fleet/backlog`, which is
|
||||
listed in `PRESERVE_PATHS` in `packages/mosaic/framework/install.sh`. This means
|
||||
`mosaic update` (which runs the framework sync with `rsync --delete`) will **not**
|
||||
wipe the operator's backlog — same protection as the roster, per-agent env, and
|
||||
heartbeat run dir.
|
||||
|
||||
## Card schema
|
||||
|
||||
A card is one row in the `backlog` table:
|
||||
|
||||
| Column | Type | Notes |
|
||||
| ------------------- | ------------------- | ------------------------------------------------------------- |
|
||||
| `id` | text (PK) | Stable, caller-supplied id (e.g. `A4`, `fleet-001`). |
|
||||
| `title` | text | Required. |
|
||||
| `body` | text (nullable) | Free-form description. |
|
||||
| `phase` | text (nullable) | Board/phase grouping (see below). |
|
||||
| `priority` | int (default 0) | **Higher = sooner.** Claim picks the max-priority ready card. |
|
||||
| `status` | enum | `ready` \| `claimed` \| `blocked` \| `done`. |
|
||||
| `depends_on` | jsonb `string[]` | DAG edges — ids of cards this one depends on. |
|
||||
| `claim_owner` | text (nullable) | Owner token of the active claim. |
|
||||
| `claim_ttl_seconds` | int (nullable) | TTL of the active claim. |
|
||||
| `claimed_at` | timestamptz (null) | When the claim was taken. `claimed_at + ttl` = expiry. |
|
||||
| `attempts` | int (default 0) | Incremented each time the card is claimed. |
|
||||
| `idempotency_key` | text (unique, null) | Dedups `create`; NULLs are distinct in Postgres. |
|
||||
| `acceptance` | jsonb (nullable) | Acceptance criteria (array of strings or object). |
|
||||
| `created_at` | timestamptz | |
|
||||
| `updated_at` | timestamptz | |
|
||||
|
||||
`depends_on` is modeled as a `jsonb` array column rather than a separate edge
|
||||
table. Justification: it matches the repo's existing style (e.g. `tasks.tags`,
|
||||
`agents.skills`, `routing_rules.conditions` are all jsonb arrays), keeps a card
|
||||
self-contained, and the DAG is small (per-card dependency lists), so a join table
|
||||
would add ceremony without benefit.
|
||||
|
||||
### Board / phase convention
|
||||
|
||||
`phase` is a free-form grouping string used as the board column / milestone label
|
||||
(e.g. `M1`, `fleet`, `infra`). `list --phase <phase>` filters to one board lane.
|
||||
`priority` orders cards **within** the ready pool regardless of phase.
|
||||
|
||||
## Status lifecycle
|
||||
|
||||
```
|
||||
create
|
||||
│
|
||||
▼
|
||||
┌──────► ready ───── claim ─────► claimed ───── complete ─────► done
|
||||
│ │ │
|
||||
│ block reclaim (TTL expiry or --id)
|
||||
│ ▼ │
|
||||
│ blocked └──────────────────────────┘ (back to ready)
|
||||
└──────────┘ (reclaim / re-create can return a card to ready)
|
||||
```
|
||||
|
||||
- **ready** — eligible to be claimed once every `depends_on` card is `done`.
|
||||
- **claimed** — a worker holds it; `claim_owner` + `claimed_at` set.
|
||||
- **blocked** — explicitly parked; never auto-claimed.
|
||||
- **done** — completed; satisfies dependents.
|
||||
|
||||
## Atomic claim (`FOR UPDATE SKIP LOCKED`) + TTL
|
||||
|
||||
`claim` is atomic. Inside a single transaction it locks candidate `ready` rows
|
||||
with `SELECT ... FOR UPDATE SKIP LOCKED` (via the drizzle `sql` operator), picks
|
||||
the highest-priority deps-satisfied card, and flips it to `claimed`. Because a row
|
||||
already locked by a concurrent claimer is **skipped**, two claimers can **never**
|
||||
both win the same card — the loser falls through to the next candidate or gets
|
||||
`null`. (Proven by the concurrency tests in `packages/db/src/backlog.spec.ts`.)
|
||||
|
||||
- **Deps gate:** a card is only claimable when every id in `depends_on` is `done`.
|
||||
- **TTL:** `claim --ttl <sec>` (default **900s**) records `claim_ttl_seconds`.
|
||||
- **reclaim:** releases claims whose `claimed_at + ttl` is in the past (expired)
|
||||
back to `ready`, clearing the claim fields. `reclaim --id <id>` force-releases a
|
||||
specific card regardless of expiry. This is how a crashed worker's card returns
|
||||
to the pool.
|
||||
|
||||
## CLI — `mosaic fleet backlog <sub> --json`
|
||||
|
||||
All subcommands support `--json`.
|
||||
|
||||
| Subcommand | Purpose |
|
||||
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `create --id --title [--body --phase --priority --depends-on --acceptance --idempotency-key]` | Create a card; `idempotency_key` dedups (repeat returns the existing card). |
|
||||
| `list [--status --phase --ready-only]` | List cards. `--ready-only` = status `ready` AND all deps `done`. |
|
||||
| `claim --owner [--ttl <sec> --id <id>]` | Atomically claim the highest-priority ready card (or `--id`). Returns the card or `null`. |
|
||||
| `reclaim [--id <id>]` | Release expired claims (or a specific card) back to `ready`. |
|
||||
| `link --from --to` | Add a `depends_on` edge (`--from` depends on `--to`). |
|
||||
| `stats` | Counts by status, oldest-ready age, expired-claim count. |
|
||||
| `block --id` | Set a card to `blocked`. |
|
||||
| `complete --id` | Set a card to `done` (releases any claim). |
|
||||
|
||||
### Example
|
||||
|
||||
```sh
|
||||
# Seed two cards, the second depends on the first.
|
||||
mosaic fleet backlog create --id A1 --title "schema" --priority 5
|
||||
mosaic fleet backlog create --id A2 --title "service" --depends-on A1 --priority 9
|
||||
|
||||
# A2 is gated on A1, so claim returns A1 first.
|
||||
mosaic fleet backlog claim --owner worker-1 --ttl 600 --json
|
||||
|
||||
# Finish A1; now A2 is ready.
|
||||
mosaic fleet backlog complete --id A1
|
||||
mosaic fleet backlog list --ready-only --json
|
||||
|
||||
# Recover stalled work.
|
||||
mosaic fleet backlog reclaim --json
|
||||
```
|
||||
@@ -1,22 +0,0 @@
|
||||
CREATE TYPE "public"."backlog_status" AS ENUM('ready', 'claimed', 'blocked', 'done');--> statement-breakpoint
|
||||
CREATE TABLE "backlog" (
|
||||
"id" text PRIMARY KEY NOT NULL,
|
||||
"title" text NOT NULL,
|
||||
"body" text,
|
||||
"phase" text,
|
||||
"priority" integer DEFAULT 0 NOT NULL,
|
||||
"status" "backlog_status" DEFAULT 'ready' NOT NULL,
|
||||
"depends_on" jsonb DEFAULT '[]'::jsonb NOT NULL,
|
||||
"claim_owner" text,
|
||||
"claim_ttl_seconds" integer,
|
||||
"claimed_at" timestamp with time zone,
|
||||
"attempts" integer DEFAULT 0 NOT NULL,
|
||||
"idempotency_key" text,
|
||||
"acceptance" jsonb,
|
||||
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
|
||||
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
|
||||
);
|
||||
--> statement-breakpoint
|
||||
CREATE INDEX "backlog_status_priority_idx" ON "backlog" USING btree ("status","priority");--> statement-breakpoint
|
||||
CREATE INDEX "backlog_status_claimed_at_idx" ON "backlog" USING btree ("status","claimed_at");--> statement-breakpoint
|
||||
CREATE UNIQUE INDEX "backlog_idempotency_key_idx" ON "backlog" USING btree ("idempotency_key");
|
||||
File diff suppressed because it is too large
Load Diff
@@ -78,13 +78,6 @@
|
||||
"when": 1745366400000,
|
||||
"tag": "0010_federation_enrollment_tokens",
|
||||
"breakpoints": true
|
||||
},
|
||||
{
|
||||
"idx": 11,
|
||||
"version": "7",
|
||||
"when": 1782310438919,
|
||||
"tag": "0011_bitter_gateway",
|
||||
"breakpoints": true
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,263 +0,0 @@
|
||||
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
|
||||
import { sql } from 'drizzle-orm';
|
||||
import { createPgliteDb } from './client-pglite.js';
|
||||
import { runPgliteMigrations } from './migrate.js';
|
||||
import type { DbHandle } from './client.js';
|
||||
import { BacklogService } from './backlog.js';
|
||||
import { backlog } from './schema.js';
|
||||
|
||||
// Helper: backdate a claim's claimed_at by 1 hour so it is past any short TTL.
|
||||
function sqlBackdate(id: string) {
|
||||
return sql`UPDATE ${backlog} SET claimed_at = now() - interval '1 hour' WHERE ${backlog.id} = ${id}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Real Postgres semantics, no external server: embedded in-memory PGlite.
|
||||
* The migration path creates the `backlog` table (and every other table) so the
|
||||
* service runs against the actual generated schema, including the row locks the
|
||||
* atomic-claim path depends on.
|
||||
*/
|
||||
async function freshService(): Promise<{ handle: DbHandle; svc: BacklogService }> {
|
||||
const handle = createPgliteDb('memory://');
|
||||
await runPgliteMigrations(handle);
|
||||
return { handle, svc: new BacklogService(handle.db) };
|
||||
}
|
||||
|
||||
describe('BacklogService', () => {
|
||||
let handle: DbHandle;
|
||||
let svc: BacklogService;
|
||||
|
||||
beforeEach(async () => {
|
||||
({ handle, svc } = await freshService());
|
||||
});
|
||||
|
||||
afterEach(async () => {
|
||||
await handle.close();
|
||||
});
|
||||
|
||||
it('create then list returns the card', async () => {
|
||||
await svc.create({ id: 'c1', title: 'First card', phase: 'M1', priority: 5 });
|
||||
const all = await svc.list();
|
||||
expect(all).toHaveLength(1);
|
||||
expect(all[0]).toMatchObject({ id: 'c1', title: 'First card', phase: 'M1', status: 'ready' });
|
||||
});
|
||||
|
||||
it('idempotency_key dedups create', async () => {
|
||||
const a = await svc.create({ id: 'c1', title: 'one', idempotencyKey: 'k-1' });
|
||||
const b = await svc.create({ id: 'c2', title: 'two', idempotencyKey: 'k-1' });
|
||||
expect(b.id).toBe(a.id);
|
||||
const all = await svc.list();
|
||||
expect(all).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('list filters by status and phase', async () => {
|
||||
await svc.create({ id: 'c1', title: 'a', phase: 'M1' });
|
||||
await svc.create({ id: 'c2', title: 'b', phase: 'M2' });
|
||||
await svc.block('c2');
|
||||
expect(await svc.list({ phase: 'M1' })).toHaveLength(1);
|
||||
expect(await svc.list({ status: 'blocked' })).toHaveLength(1);
|
||||
expect((await svc.list({ status: 'blocked' }))[0]!.id).toBe('c2');
|
||||
});
|
||||
|
||||
describe('atomic claim', () => {
|
||||
it('two concurrent claimers on one card => exactly one wins', async () => {
|
||||
await svc.create({ id: 'only', title: 'the one', priority: 10 });
|
||||
|
||||
// Two independent claimers race for the single ready card on the same db.
|
||||
// The atomic claim path (`FOR UPDATE SKIP LOCKED` inside a transaction)
|
||||
// guarantees the loser's locked row is skipped, so it can never also flip
|
||||
// the card to claimed — it gets the next candidate (none) and returns null.
|
||||
const svcA = new BacklogService(handle.db);
|
||||
const svcB = new BacklogService(handle.db);
|
||||
|
||||
const [a, b] = await Promise.all([
|
||||
svcA.claim({ owner: 'worker-A' }),
|
||||
svcB.claim({ owner: 'worker-B' }),
|
||||
]);
|
||||
|
||||
const winners = [a, b].filter((c) => c !== null);
|
||||
expect(winners).toHaveLength(1);
|
||||
expect(winners[0]!.id).toBe('only');
|
||||
expect(winners[0]!.status).toBe('claimed');
|
||||
expect(['worker-A', 'worker-B']).toContain(winners[0]!.claimOwner);
|
||||
|
||||
const card = await svc.get('only');
|
||||
expect(card!.status).toBe('claimed');
|
||||
expect(card!.attempts).toBe(1);
|
||||
});
|
||||
|
||||
it('many concurrent claimers on N cards => no card is double-claimed', async () => {
|
||||
// 5 ready cards, 8 concurrent claimers. Exactly 5 win, all distinct.
|
||||
for (let i = 0; i < 5; i++) {
|
||||
await svc.create({ id: `card-${i}`, title: `card ${i}`, priority: i });
|
||||
}
|
||||
const claimers = Array.from({ length: 8 }, (_, i) =>
|
||||
new BacklogService(handle.db).claim({ owner: `w-${i}` }),
|
||||
);
|
||||
const results = await Promise.all(claimers);
|
||||
const won = results.filter((c): c is NonNullable<typeof c> => c !== null);
|
||||
const wonIds = won.map((c) => c.id);
|
||||
expect(won).toHaveLength(5);
|
||||
expect(new Set(wonIds).size).toBe(5); // all distinct — no double-claim
|
||||
});
|
||||
|
||||
it('N concurrent claimers on N ready cards => every claimer wins a distinct card (no starvation)', async () => {
|
||||
// This is the direct benefit of locking exactly ONE ready row per claim
|
||||
// (`FOR UPDATE SKIP LOCKED LIMIT 1`): with as many ready cards as
|
||||
// claimers, NONE should starve. The old "lock the whole ready set"
|
||||
// behaviour let one claimer lock every row, forcing the rest to null even
|
||||
// though cards were free.
|
||||
const N = 6;
|
||||
for (let i = 0; i < N; i++) {
|
||||
await svc.create({ id: `n-${i}`, title: `card ${i}`, priority: i });
|
||||
}
|
||||
const results = await Promise.all(
|
||||
Array.from({ length: N }, (_, i) =>
|
||||
new BacklogService(handle.db).claim({ owner: `w-${i}` }),
|
||||
),
|
||||
);
|
||||
const won = results.filter((c): c is NonNullable<typeof c> => c !== null);
|
||||
// No claimer starved: all N won.
|
||||
expect(won).toHaveLength(N);
|
||||
// Each won a distinct card.
|
||||
expect(new Set(won.map((c) => c.id)).size).toBe(N);
|
||||
// Every ready card was consumed.
|
||||
expect(await svc.list({ status: 'ready' })).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('sequential claims drain ready cards in priority order and never null while ready remain', async () => {
|
||||
// PGlite-stable fallback assertion of the same property without relying on
|
||||
// true parallelism or wall-clock timing: each claim returns the next
|
||||
// highest-priority distinct card and never spuriously returns null while
|
||||
// ready cards remain.
|
||||
const N = 4;
|
||||
for (let i = 0; i < N; i++) {
|
||||
await svc.create({ id: `s-${i}`, title: `card ${i}`, priority: i });
|
||||
}
|
||||
const order: string[] = [];
|
||||
for (let i = 0; i < N; i++) {
|
||||
const claimed = await svc.claim({ owner: `w-${i}` });
|
||||
expect(claimed).not.toBeNull();
|
||||
order.push(claimed!.id);
|
||||
}
|
||||
// Highest priority first, all distinct.
|
||||
expect(order).toEqual(['s-3', 's-2', 's-1', 's-0']);
|
||||
expect(new Set(order).size).toBe(N);
|
||||
// Now nothing ready remains => null.
|
||||
expect(await svc.claim({ owner: 'late' })).toBeNull();
|
||||
});
|
||||
|
||||
it('claim picks the highest-priority ready card', async () => {
|
||||
await svc.create({ id: 'low', title: 'low', priority: 1 });
|
||||
await svc.create({ id: 'high', title: 'high', priority: 9 });
|
||||
const claimed = await svc.claim({ owner: 'w' });
|
||||
expect(claimed!.id).toBe('high');
|
||||
});
|
||||
|
||||
it('claim of a specific --id', async () => {
|
||||
await svc.create({ id: 'a', title: 'a', priority: 9 });
|
||||
await svc.create({ id: 'b', title: 'b', priority: 1 });
|
||||
const claimed = await svc.claim({ owner: 'w', id: 'b' });
|
||||
expect(claimed!.id).toBe('b');
|
||||
});
|
||||
|
||||
it('claim returns null when nothing is ready', async () => {
|
||||
const claimed = await svc.claim({ owner: 'w' });
|
||||
expect(claimed).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('deps DAG gate', () => {
|
||||
it('card with an unfinished dep is not claimable and not ready', async () => {
|
||||
await svc.create({ id: 'dep', title: 'dependency' });
|
||||
await svc.create({ id: 'main', title: 'depends on dep', dependsOn: ['dep'] });
|
||||
|
||||
// `main` should NOT be claimable while `dep` is not done — `dep` wins.
|
||||
const first = await svc.claim({ owner: 'w' });
|
||||
expect(first!.id).toBe('dep');
|
||||
|
||||
// With dep claimed (not done), main still cannot be claimed.
|
||||
const second = await svc.claim({ owner: 'w' });
|
||||
expect(second).toBeNull();
|
||||
|
||||
// ready-only list excludes main while its dep is unfinished.
|
||||
const ready = await svc.list({ readyOnly: true });
|
||||
expect(ready.map((c) => c.id)).not.toContain('main');
|
||||
|
||||
// Once dep is done, main becomes ready and claimable.
|
||||
await svc.complete('dep');
|
||||
const readyAfter = await svc.list({ readyOnly: true });
|
||||
expect(readyAfter.map((c) => c.id)).toContain('main');
|
||||
const third = await svc.claim({ owner: 'w' });
|
||||
expect(third!.id).toBe('main');
|
||||
});
|
||||
|
||||
it('link adds a depends_on edge', async () => {
|
||||
await svc.create({ id: 'a', title: 'a' });
|
||||
await svc.create({ id: 'b', title: 'b' });
|
||||
const linked = await svc.link('a', 'b');
|
||||
expect(linked.dependsOn).toEqual(['b']);
|
||||
// a is now gated on b
|
||||
const claimed = await svc.claim({ owner: 'w' });
|
||||
expect(claimed!.id).toBe('b');
|
||||
});
|
||||
});
|
||||
|
||||
describe('reclaim TTL', () => {
|
||||
it('reclaim returns expired claims to ready', async () => {
|
||||
await svc.create({ id: 'c1', title: 'c1' });
|
||||
const claimed = await svc.claim({ owner: 'w', ttlSeconds: 60 });
|
||||
expect(claimed!.status).toBe('claimed');
|
||||
|
||||
// Backdate the claim so it is well past its TTL.
|
||||
await handle.db.execute(sqlBackdate('c1'));
|
||||
|
||||
const result = await svc.reclaim();
|
||||
expect(result.reclaimed).toEqual(['c1']);
|
||||
const card = await svc.get('c1');
|
||||
expect(card!.status).toBe('ready');
|
||||
expect(card!.claimOwner).toBeNull();
|
||||
expect(card!.claimedAt).toBeNull();
|
||||
});
|
||||
|
||||
it('reclaim does not touch a fresh (unexpired) claim', async () => {
|
||||
await svc.create({ id: 'c1', title: 'c1' });
|
||||
await svc.claim({ owner: 'w', ttlSeconds: 3600 });
|
||||
const result = await svc.reclaim();
|
||||
expect(result.reclaimed).toEqual([]);
|
||||
expect((await svc.get('c1'))!.status).toBe('claimed');
|
||||
});
|
||||
|
||||
it('reclaim --id releases a specific claim regardless of expiry', async () => {
|
||||
await svc.create({ id: 'c1', title: 'c1' });
|
||||
await svc.claim({ owner: 'w', ttlSeconds: 3600 });
|
||||
const result = await svc.reclaim({ id: 'c1' });
|
||||
expect(result.reclaimed).toEqual(['c1']);
|
||||
expect((await svc.get('c1'))!.status).toBe('ready');
|
||||
});
|
||||
});
|
||||
|
||||
describe('stats', () => {
|
||||
it('computes counts, oldest-ready age, and expired-claim count', async () => {
|
||||
await svc.create({ id: 'r1', title: 'r1' });
|
||||
await svc.create({ id: 'r2', title: 'r2' });
|
||||
await svc.create({ id: 'b1', title: 'b1' });
|
||||
await svc.block('b1');
|
||||
await svc.create({ id: 'd1', title: 'd1' });
|
||||
await svc.complete('d1');
|
||||
await svc.create({ id: 'cl1', title: 'cl1' });
|
||||
await svc.claim({ owner: 'w', id: 'cl1', ttlSeconds: 60 });
|
||||
await handle.db.execute(sqlBackdate('cl1'));
|
||||
|
||||
const stats = await svc.stats();
|
||||
expect(stats.counts.ready).toBe(2);
|
||||
expect(stats.counts.blocked).toBe(1);
|
||||
expect(stats.counts.done).toBe(1);
|
||||
expect(stats.counts.claimed).toBe(1);
|
||||
expect(stats.total).toBe(5);
|
||||
expect(stats.expiredClaimCount).toBe(1);
|
||||
expect(stats.oldestReadyAgeSeconds).not.toBeNull();
|
||||
expect(stats.oldestReadyAgeSeconds!).toBeGreaterThanOrEqual(0);
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -1,457 +0,0 @@
|
||||
/**
|
||||
* Mosaic-native backlog-of-record service (card A4).
|
||||
*
|
||||
* This is the backlog Mosaic owns end-to-end on its OWN Postgres storage layer.
|
||||
* It REPLACES the former Hermes adapter — there is NO runtime dependency on
|
||||
* Hermes here or anywhere downstream.
|
||||
*
|
||||
* The service takes a `Db` handle, so it works identically against:
|
||||
* - `createDb()` — server Postgres (DATABASE_URL / config), and
|
||||
* - `createPgliteDb()` — embedded Postgres (file or in-memory).
|
||||
* Same code, same semantics — PGlite gives real Postgres behaviour (including
|
||||
* row locks), so the atomic-claim path is exercised by the in-memory tests.
|
||||
*
|
||||
* Atomic claim: `claim()` selects the highest-priority, deps-satisfied, ready
|
||||
* card with `SELECT ... FOR UPDATE SKIP LOCKED` and flips it to `claimed` inside
|
||||
* one transaction. Two concurrent claimers can therefore NEVER both win the same
|
||||
* card — the loser's locked row is skipped and it picks the next candidate (or
|
||||
* gets null).
|
||||
*/
|
||||
|
||||
import { and, asc, desc, eq, sql } from 'drizzle-orm';
|
||||
import type { Db } from './client.js';
|
||||
import { backlog } from './schema.js';
|
||||
|
||||
export type BacklogStatus = 'ready' | 'claimed' | 'blocked' | 'done';
|
||||
|
||||
export interface BacklogCard {
|
||||
id: string;
|
||||
title: string;
|
||||
body: string | null;
|
||||
phase: string | null;
|
||||
priority: number;
|
||||
status: BacklogStatus;
|
||||
dependsOn: string[];
|
||||
claimOwner: string | null;
|
||||
claimTtlSeconds: number | null;
|
||||
claimedAt: Date | null;
|
||||
attempts: number;
|
||||
idempotencyKey: string | null;
|
||||
acceptance: unknown;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
}
|
||||
|
||||
export interface CreateCardInput {
|
||||
id: string;
|
||||
title: string;
|
||||
body?: string | null;
|
||||
phase?: string | null;
|
||||
priority?: number;
|
||||
dependsOn?: string[];
|
||||
acceptance?: unknown;
|
||||
idempotencyKey?: string | null;
|
||||
status?: BacklogStatus;
|
||||
}
|
||||
|
||||
export interface ListFilter {
|
||||
status?: BacklogStatus;
|
||||
phase?: string;
|
||||
/** When true, return only cards that are `ready` AND have all deps `done`. */
|
||||
readyOnly?: boolean;
|
||||
}
|
||||
|
||||
export interface ClaimOptions {
|
||||
owner: string;
|
||||
/** Claim time-to-live in seconds (default 900). */
|
||||
ttlSeconds?: number;
|
||||
/** Claim a specific card by id instead of the highest-priority ready one. */
|
||||
id?: string;
|
||||
}
|
||||
|
||||
export interface ReclaimResult {
|
||||
reclaimed: string[];
|
||||
}
|
||||
|
||||
export interface BacklogStats {
|
||||
counts: Record<BacklogStatus, number>;
|
||||
total: number;
|
||||
oldestReadyAgeSeconds: number | null;
|
||||
expiredClaimCount: number;
|
||||
}
|
||||
|
||||
export const DEFAULT_CLAIM_TTL_SECONDS = 900;
|
||||
|
||||
type Row = typeof backlog.$inferSelect;
|
||||
|
||||
/**
|
||||
* Row shape as returned by the raw `SELECT * ... FOR UPDATE SKIP LOCKED` path.
|
||||
* That path bypasses drizzle's column-name mapping, so JSON columns arrive as
|
||||
* the snake_case `depends_on` (and may be a JSON string under some drivers).
|
||||
*/
|
||||
interface RawRow extends Row {
|
||||
depends_on?: unknown;
|
||||
}
|
||||
|
||||
function toCard(row: Row): BacklogCard {
|
||||
return {
|
||||
id: row.id,
|
||||
title: row.title,
|
||||
body: row.body,
|
||||
phase: row.phase,
|
||||
priority: row.priority,
|
||||
status: row.status,
|
||||
dependsOn: row.dependsOn ?? [],
|
||||
claimOwner: row.claimOwner,
|
||||
claimTtlSeconds: row.claimTtlSeconds,
|
||||
claimedAt: row.claimedAt,
|
||||
attempts: row.attempts,
|
||||
idempotencyKey: row.idempotencyKey,
|
||||
acceptance: row.acceptance,
|
||||
createdAt: row.createdAt,
|
||||
updatedAt: row.updatedAt,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* The backlog repository/service. Construct with any `Db` handle.
|
||||
*/
|
||||
export class BacklogService {
|
||||
constructor(private readonly db: Db) {}
|
||||
|
||||
/**
|
||||
* Create a card. If `idempotencyKey` is provided and a card already exists
|
||||
* with that key, the existing card is returned unchanged (no duplicate).
|
||||
*/
|
||||
async create(input: CreateCardInput): Promise<BacklogCard> {
|
||||
if (input.idempotencyKey) {
|
||||
const existing = await this.db
|
||||
.select()
|
||||
.from(backlog)
|
||||
.where(eq(backlog.idempotencyKey, input.idempotencyKey))
|
||||
.limit(1);
|
||||
if (existing[0]) return toCard(existing[0]);
|
||||
}
|
||||
|
||||
const inserted = await this.db
|
||||
.insert(backlog)
|
||||
.values({
|
||||
id: input.id,
|
||||
title: input.title,
|
||||
body: input.body ?? null,
|
||||
phase: input.phase ?? null,
|
||||
priority: input.priority ?? 0,
|
||||
status: input.status ?? 'ready',
|
||||
dependsOn: input.dependsOn ?? [],
|
||||
acceptance: input.acceptance ?? null,
|
||||
idempotencyKey: input.idempotencyKey ?? null,
|
||||
})
|
||||
.returning();
|
||||
|
||||
return toCard(inserted[0]!);
|
||||
}
|
||||
|
||||
/** Fetch a single card by id, or null. */
|
||||
async get(id: string): Promise<BacklogCard | null> {
|
||||
const rows = await this.db.select().from(backlog).where(eq(backlog.id, id)).limit(1);
|
||||
return rows[0] ? toCard(rows[0]) : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* List cards with optional filters. `readyOnly` enforces the DAG gate:
|
||||
* a card is "ready" only when its own status is `ready` AND every card in
|
||||
* `depends_on` exists and is `done`.
|
||||
*/
|
||||
async list(filter: ListFilter = {}): Promise<BacklogCard[]> {
|
||||
const conditions = [];
|
||||
if (filter.status) conditions.push(eq(backlog.status, filter.status));
|
||||
if (filter.phase) conditions.push(eq(backlog.phase, filter.phase));
|
||||
|
||||
const rows = await this.db
|
||||
.select()
|
||||
.from(backlog)
|
||||
.where(conditions.length ? and(...conditions) : undefined)
|
||||
.orderBy(desc(backlog.priority), asc(backlog.createdAt));
|
||||
|
||||
const cards = rows.map(toCard);
|
||||
if (!filter.readyOnly) return cards;
|
||||
|
||||
const doneIds = await this.doneIdSet();
|
||||
return cards.filter(
|
||||
(c) => c.status === 'ready' && c.dependsOn.every((dep) => doneIds.has(dep)),
|
||||
);
|
||||
}
|
||||
|
||||
private async doneIdSet(): Promise<Set<string>> {
|
||||
const done = await this.db
|
||||
.select({ id: backlog.id })
|
||||
.from(backlog)
|
||||
.where(eq(backlog.status, 'done'));
|
||||
return new Set(done.map((d) => d.id));
|
||||
}
|
||||
|
||||
/**
|
||||
* Atomically claim a card.
|
||||
*
|
||||
* Strategy: inside ONE transaction we lock the candidate row with
|
||||
* `FOR UPDATE SKIP LOCKED LIMIT 1`. A concurrent claimer that already holds
|
||||
* the lock on a row has that row skipped for us, so two claimers can never
|
||||
* both win the same card — and, crucially, each claimer locks exactly ONE
|
||||
* row, so concurrent claimers fan out across distinct ready cards instead of
|
||||
* one claimer locking the whole ready set and starving the rest.
|
||||
*
|
||||
* Candidate selection (when no explicit `id`):
|
||||
* - status = 'ready'
|
||||
* - all deps satisfied (every id in depends_on is currently 'done')
|
||||
* - ordered by priority DESC, created_at ASC
|
||||
*
|
||||
* Returns the claimed card, or null if nothing is claimable.
|
||||
*/
|
||||
async claim(opts: ClaimOptions): Promise<BacklogCard | null> {
|
||||
const ttl = opts.ttlSeconds ?? DEFAULT_CLAIM_TTL_SECONDS;
|
||||
|
||||
return this.db.transaction(async (tx) => {
|
||||
// Specific-id path: lock that one ready row (if free) and apply the
|
||||
// deps-satisfied gate in JS, exactly as before.
|
||||
if (opts.id) {
|
||||
const doneRows = await tx
|
||||
.select({ id: backlog.id })
|
||||
.from(backlog)
|
||||
.where(eq(backlog.status, 'done'));
|
||||
const doneIds = new Set(doneRows.map((r) => r.id));
|
||||
|
||||
const result = await tx.execute(
|
||||
sql`SELECT * FROM ${backlog}
|
||||
WHERE ${backlog.id} = ${opts.id} AND ${backlog.status} = 'ready'
|
||||
FOR UPDATE SKIP LOCKED`,
|
||||
);
|
||||
const candidate = rowsOf(result).find((row) =>
|
||||
normalizeDeps(row.depends_on).every((dep) => doneIds.has(dep)),
|
||||
);
|
||||
if (!candidate) return null;
|
||||
|
||||
const updated = await tx
|
||||
.update(backlog)
|
||||
.set({
|
||||
status: 'claimed',
|
||||
claimOwner: opts.owner,
|
||||
claimTtlSeconds: ttl,
|
||||
claimedAt: new Date(),
|
||||
attempts: sql`${backlog.attempts} + 1`,
|
||||
updatedAt: new Date(),
|
||||
})
|
||||
.where(eq(backlog.id, candidate.id))
|
||||
.returning();
|
||||
|
||||
return toCard(updated[0]!);
|
||||
}
|
||||
|
||||
// No-id path: claim the single highest-priority, deps-satisfied ready
|
||||
// card. We lock exactly ONE row in the inner SELECT (`FOR UPDATE SKIP
|
||||
// LOCKED LIMIT 1`) so concurrent claimers grab distinct cards rather than
|
||||
// one claimer locking every ready row and forcing the others to null.
|
||||
//
|
||||
// The deps-satisfied gate is pushed into SQL so `LIMIT 1` lands on the
|
||||
// next genuinely-eligible card: a card is eligible iff none of its
|
||||
// depends_on ids is absent from the set of 'done' card ids.
|
||||
const updated = await tx.execute(
|
||||
sql`UPDATE ${backlog}
|
||||
SET status = 'claimed',
|
||||
claim_owner = ${opts.owner},
|
||||
claim_ttl_seconds = ${ttl},
|
||||
claimed_at = now(),
|
||||
attempts = ${backlog.attempts} + 1,
|
||||
updated_at = now()
|
||||
WHERE ${backlog.id} = (
|
||||
SELECT b.id FROM ${backlog} AS b
|
||||
WHERE b.status = 'ready'
|
||||
AND NOT EXISTS (
|
||||
SELECT 1
|
||||
FROM jsonb_array_elements_text(b.depends_on) AS dep
|
||||
WHERE dep NOT IN (
|
||||
SELECT d.id FROM ${backlog} AS d WHERE d.status = 'done'
|
||||
)
|
||||
)
|
||||
ORDER BY b.priority DESC, b.created_at ASC
|
||||
FOR UPDATE SKIP LOCKED
|
||||
LIMIT 1
|
||||
)
|
||||
RETURNING *`,
|
||||
);
|
||||
|
||||
const row = rowsOf(updated)[0];
|
||||
return row ? toCard(rawToRow(row)) : null;
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Release expired claims (claimed_at + ttl < now) back to `ready`, OR release
|
||||
* a specific card by id regardless of expiry. Cleared claim fields.
|
||||
* Returns the ids that were released.
|
||||
*/
|
||||
async reclaim(opts: { id?: string } = {}): Promise<ReclaimResult> {
|
||||
if (opts.id) {
|
||||
const released = await this.db
|
||||
.update(backlog)
|
||||
.set({
|
||||
status: 'ready',
|
||||
claimOwner: null,
|
||||
claimTtlSeconds: null,
|
||||
claimedAt: null,
|
||||
updatedAt: new Date(),
|
||||
})
|
||||
.where(and(eq(backlog.id, opts.id), eq(backlog.status, 'claimed')))
|
||||
.returning({ id: backlog.id });
|
||||
return { reclaimed: released.map((r) => r.id) };
|
||||
}
|
||||
|
||||
// Expired = status claimed AND claimed_at + (ttl seconds) < now().
|
||||
const released = await this.db
|
||||
.update(backlog)
|
||||
.set({
|
||||
status: 'ready',
|
||||
claimOwner: null,
|
||||
claimTtlSeconds: null,
|
||||
claimedAt: null,
|
||||
updatedAt: new Date(),
|
||||
})
|
||||
.where(
|
||||
and(
|
||||
eq(backlog.status, 'claimed'),
|
||||
sql`${backlog.claimedAt} + make_interval(secs => ${backlog.claimTtlSeconds}) < now()`,
|
||||
),
|
||||
)
|
||||
.returning({ id: backlog.id });
|
||||
return { reclaimed: released.map((r) => r.id) };
|
||||
}
|
||||
|
||||
/** Add a `depends_on` edge (from → depends on → to). Idempotent. */
|
||||
async link(from: string, to: string): Promise<BacklogCard> {
|
||||
const card = await this.get(from);
|
||||
if (!card) throw new Error(`backlog card not found: ${from}`);
|
||||
const target = await this.get(to);
|
||||
if (!target) throw new Error(`backlog dependency not found: ${to}`);
|
||||
if (from === to) throw new Error('a card cannot depend on itself');
|
||||
|
||||
if (card.dependsOn.includes(to)) return card;
|
||||
const nextDeps = [...card.dependsOn, to];
|
||||
const updated = await this.db
|
||||
.update(backlog)
|
||||
.set({ dependsOn: nextDeps, updatedAt: new Date() })
|
||||
.where(eq(backlog.id, from))
|
||||
.returning();
|
||||
return toCard(updated[0]!);
|
||||
}
|
||||
|
||||
/** Mark a card blocked. */
|
||||
async block(id: string): Promise<BacklogCard | null> {
|
||||
return this.setStatus(id, 'blocked');
|
||||
}
|
||||
|
||||
/** Mark a card done (releasing any claim). */
|
||||
async complete(id: string): Promise<BacklogCard | null> {
|
||||
const updated = await this.db
|
||||
.update(backlog)
|
||||
.set({
|
||||
status: 'done',
|
||||
claimOwner: null,
|
||||
claimTtlSeconds: null,
|
||||
claimedAt: null,
|
||||
updatedAt: new Date(),
|
||||
})
|
||||
.where(eq(backlog.id, id))
|
||||
.returning();
|
||||
return updated[0] ? toCard(updated[0]) : null;
|
||||
}
|
||||
|
||||
private async setStatus(id: string, status: BacklogStatus): Promise<BacklogCard | null> {
|
||||
const updated = await this.db
|
||||
.update(backlog)
|
||||
.set({ status, updatedAt: new Date() })
|
||||
.where(eq(backlog.id, id))
|
||||
.returning();
|
||||
return updated[0] ? toCard(updated[0]) : null;
|
||||
}
|
||||
|
||||
/** Counts by status, oldest-ready age (seconds), and expired-claim count. */
|
||||
async stats(): Promise<BacklogStats> {
|
||||
const all = await this.db.select().from(backlog);
|
||||
const counts: Record<BacklogStatus, number> = {
|
||||
ready: 0,
|
||||
claimed: 0,
|
||||
blocked: 0,
|
||||
done: 0,
|
||||
};
|
||||
let oldestReady: Date | null = null;
|
||||
let expiredClaimCount = 0;
|
||||
const now = Date.now();
|
||||
|
||||
for (const row of all) {
|
||||
counts[row.status] += 1;
|
||||
if (row.status === 'ready') {
|
||||
if (oldestReady === null || row.createdAt < oldestReady) oldestReady = row.createdAt;
|
||||
}
|
||||
if (row.status === 'claimed' && row.claimedAt && row.claimTtlSeconds != null) {
|
||||
const expiry = row.claimedAt.getTime() + row.claimTtlSeconds * 1000;
|
||||
if (expiry < now) expiredClaimCount += 1;
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
counts,
|
||||
total: all.length,
|
||||
oldestReadyAgeSeconds:
|
||||
oldestReady === null ? null : Math.max(0, Math.floor((now - oldestReady.getTime()) / 1000)),
|
||||
expiredClaimCount,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
/** Extract rows from a drizzle `.execute()` result across drivers (pg / pglite). */
|
||||
function rowsOf(result: unknown): RawRow[] {
|
||||
if (Array.isArray(result)) return result as RawRow[];
|
||||
const maybe = result as { rows?: unknown };
|
||||
if (maybe && Array.isArray(maybe.rows)) return maybe.rows as RawRow[];
|
||||
return [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Map a raw `RETURNING *` row (snake_case columns, possibly string-encoded
|
||||
* timestamps/JSON depending on the driver) onto the drizzle `Row` shape that
|
||||
* `toCard` consumes. Mirrors the column ↔ property mapping in `schema.ts`.
|
||||
*/
|
||||
function rawToRow(raw: RawRow): Row {
|
||||
const r = raw as unknown as Record<string, unknown>;
|
||||
const toDate = (v: unknown): Date => (v instanceof Date ? v : new Date(v as string));
|
||||
return {
|
||||
id: r.id as string,
|
||||
title: r.title as string,
|
||||
body: (r.body ?? null) as string | null,
|
||||
phase: (r.phase ?? null) as string | null,
|
||||
priority: Number(r.priority),
|
||||
status: r.status as BacklogStatus,
|
||||
dependsOn: normalizeDeps(r.depends_on),
|
||||
claimOwner: (r.claim_owner ?? null) as string | null,
|
||||
claimTtlSeconds: r.claim_ttl_seconds == null ? null : Number(r.claim_ttl_seconds),
|
||||
claimedAt: r.claimed_at == null ? null : toDate(r.claimed_at),
|
||||
attempts: Number(r.attempts),
|
||||
idempotencyKey: (r.idempotency_key ?? null) as string | null,
|
||||
acceptance: r.acceptance ?? null,
|
||||
createdAt: toDate(r.created_at),
|
||||
updatedAt: toDate(r.updated_at),
|
||||
};
|
||||
}
|
||||
|
||||
/** A raw SQL row returns snake_case `depends_on`; normalize to string[]. */
|
||||
function normalizeDeps(value: unknown): string[] {
|
||||
if (Array.isArray(value)) return value as string[];
|
||||
if (typeof value === 'string') {
|
||||
try {
|
||||
const parsed = JSON.parse(value);
|
||||
return Array.isArray(parsed) ? (parsed as string[]) : [];
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
return [];
|
||||
}
|
||||
@@ -3,17 +3,6 @@ export { createPgliteDb } from './client-pglite.js';
|
||||
export { runMigrations, runPgliteMigrations } from './migrate.js';
|
||||
export * from './schema.js';
|
||||
export * from './federation.js';
|
||||
export {
|
||||
BacklogService,
|
||||
DEFAULT_CLAIM_TTL_SECONDS,
|
||||
type BacklogCard,
|
||||
type BacklogStatus,
|
||||
type BacklogStats,
|
||||
type ClaimOptions,
|
||||
type CreateCardInput,
|
||||
type ListFilter,
|
||||
type ReclaimResult,
|
||||
} from './backlog.js';
|
||||
export {
|
||||
eq,
|
||||
and,
|
||||
|
||||
@@ -587,62 +587,6 @@ export const summarizationJobs = pgTable(
|
||||
(t) => [index('summarization_jobs_status_idx').on(t.status)],
|
||||
);
|
||||
|
||||
// ─── Fleet Backlog ────────────────────────────────────────────────────────────
|
||||
// Mosaic-native backlog-of-record (card A4). This REPLACES the former Hermes
|
||||
// adapter — there is NO runtime dependency on Hermes. Cards form a dependency
|
||||
// DAG (`depends_on`), are claimed atomically by fleet workers via
|
||||
// `SELECT ... FOR UPDATE SKIP LOCKED`, and auto-expire via a TTL so a crashed
|
||||
// claimer's card returns to the pool.
|
||||
|
||||
/**
|
||||
* Lifecycle status of a backlog card.
|
||||
* - ready: eligible to be claimed (once its deps are all `done`).
|
||||
* - claimed: a worker holds it (claim_owner + claimed_at set); may expire via TTL.
|
||||
* - blocked: explicitly parked; never auto-claimed.
|
||||
* - done: completed; satisfies dependents.
|
||||
*/
|
||||
export const backlogStatusEnum = pgEnum('backlog_status', ['ready', 'claimed', 'blocked', 'done']);
|
||||
|
||||
export const backlog = pgTable(
|
||||
'backlog',
|
||||
{
|
||||
/** Stable, caller-supplied card id (e.g. "A4", "fleet-001"). PK. */
|
||||
id: text('id').primaryKey(),
|
||||
title: text('title').notNull(),
|
||||
body: text('body'),
|
||||
/** Board/phase grouping (e.g. "M1", "fleet"). Free-form. */
|
||||
phase: text('phase'),
|
||||
/** Higher number = higher priority; claim picks the max-priority ready card. */
|
||||
priority: integer('priority').notNull().default(0),
|
||||
status: backlogStatusEnum('status').notNull().default('ready'),
|
||||
/** DAG edges: ids of cards this one depends on. "ready" requires all done. */
|
||||
dependsOn: jsonb('depends_on').notNull().$type<string[]>().default([]),
|
||||
/** Owner token of the current claim (worker/agent id). NULL when unclaimed. */
|
||||
claimOwner: text('claim_owner'),
|
||||
/** TTL of the active claim in seconds. NULL when unclaimed. */
|
||||
claimTtlSeconds: integer('claim_ttl_seconds'),
|
||||
/** When the active claim was taken. NULL when unclaimed. claimed_at + ttl = expiry. */
|
||||
claimedAt: timestamp('claimed_at', { withTimezone: true }),
|
||||
/** Count of times this card has been claimed (incremented on each claim). */
|
||||
attempts: integer('attempts').notNull().default(0),
|
||||
/** Optional dedup key for `create`; a repeat key returns the existing card. */
|
||||
idempotencyKey: text('idempotency_key'),
|
||||
/** Acceptance criteria — free-form JSON (array of strings or object). */
|
||||
acceptance: jsonb('acceptance'),
|
||||
createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
|
||||
updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
|
||||
},
|
||||
(t) => [
|
||||
// Hot path: claim scans ready cards ordered by priority then age.
|
||||
index('backlog_status_priority_idx').on(t.status, t.priority),
|
||||
// reclaim sweeps claimed cards by claimed_at to find expired ones.
|
||||
index('backlog_status_claimed_at_idx').on(t.status, t.claimedAt),
|
||||
// Idempotent create dedups on this key (NULLs are distinct in Postgres, so
|
||||
// many unkeyed cards coexist; a repeated non-null key collides).
|
||||
uniqueIndex('backlog_idempotency_key_idx').on(t.idempotencyKey),
|
||||
],
|
||||
);
|
||||
|
||||
// ─── Federation ──────────────────────────────────────────────────────────────
|
||||
// Enums declared before tables that reference them.
|
||||
// All federation definitions live in this file (avoids CJS/ESM cross-import
|
||||
|
||||
@@ -1,38 +0,0 @@
|
||||
# Board — fleet role definition
|
||||
|
||||
The **board** is the fleet's **deliberation panel** (`class: board`). It is the
|
||||
forge **Board-of-Directors** reused as a fleet role — a multi-lens review body
|
||||
(moonshot, contrarian, technical, business, financial) that owns the mission's
|
||||
direction, not its execution.
|
||||
|
||||
It is a **front-office** role: it sets and guards intent, then steps back.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Own `NORTH_STAR.yaml`** — the single source of truth for goals, assumptions,
|
||||
and projections. The board is the only role that ratifies edits to it.
|
||||
2. **Ratify or veto goals and assumptions** — every new objective or load-bearing
|
||||
assumption passes the board's lenses before the fleet commits resources to it.
|
||||
3. **Hold the lenses** — moonshot (is the ambition right?), contrarian (what breaks
|
||||
this?), technical (is it buildable?), business (does it matter?), financial
|
||||
(can we afford it, in tokens and dollars?).
|
||||
4. **Re-deliberate on drift** — when results diverge from the north star, the board
|
||||
reconvenes, re-ratifies or vetoes, and updates `NORTH_STAR.yaml`.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT write product/source code.**
|
||||
- **Does NOT merge.**
|
||||
- **Does NOT decompose, plan phases, or dispatch tasks** — it ratifies the
|
||||
_what_ and _why_; planner and decomposition own the _how_.
|
||||
|
||||
The board deliberates and decides direction; it never touches the working tree or
|
||||
the merge path. When it approves a goal, the planner expands it.
|
||||
|
||||
## Persona
|
||||
|
||||
A standing panel of senior voices, each arguing from a fixed vantage. The board is
|
||||
deliberately slow and adversarial — its value is catching the expensive mistake
|
||||
before a single agent-hour is spent on it.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` ('board' role = forge BOD; role library).
|
||||
@@ -1,36 +0,0 @@
|
||||
# Code — fleet role definition
|
||||
|
||||
The **code** role is the fleet's primary **executor** (`class: code`). It picks up
|
||||
one decomposition card and implements it to green CI on a branch, then opens a PR.
|
||||
|
||||
It is an **execution** role: one card, one branch, one PR.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Implement one card to green CI** — take a single backlog card and make the
|
||||
change it describes, on a dedicated branch, until the project's gates
|
||||
(typecheck, lint, format, tests) pass.
|
||||
2. **Open the PR via `pr-create.sh`** — once gates are green, open exactly one
|
||||
pull request for the card using the standard `pr-create.sh` wrapper.
|
||||
3. **Stay in card scope** — touch only the files the card calls for. No scope
|
||||
creep, no opportunistic refactors outside the card's boundary.
|
||||
4. **One card = one PR** — honor the decomposition contract: a card becomes a
|
||||
single focused PR, never two, and a PR never bundles two cards.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT merge.** Opening the PR is the end of the code role's authority; the
|
||||
**merge-gate** role is the only approver/merger.
|
||||
- **Does NOT approve or self-review** — correctness sign-off belongs to the
|
||||
**review** and **security-review** roles.
|
||||
- **Does NOT decompose or re-plan** — if a card is wrong or too large, it escalates
|
||||
rather than silently re-scoping.
|
||||
|
||||
The code role writes the change and opens the PR; it never touches the merge path.
|
||||
|
||||
## Persona
|
||||
|
||||
The focused builder. It takes one well-scoped card, drives it to green, opens a
|
||||
clean PR, and hands off — never reaching past the card it was given.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` (role library).
|
||||
@@ -1,38 +0,0 @@
|
||||
# Decomposition — fleet role definition
|
||||
|
||||
The **decomposition** role splits the planner's FRs into **one-PR-each cards**,
|
||||
wired together with `depends_on` link edges, ready for the code role to pick up.
|
||||
|
||||
It is a **front-office** role.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Drive the native `mosaic fleet backlog`** — decomposition is the operator of
|
||||
Mosaic's own backlog; it creates and links cards there, on Mosaic's storage
|
||||
layer. It does NOT hand-roll a parallel splitter and does NOT call any external
|
||||
kanban service.
|
||||
2. **One card = one PR** — each emitted card is scoped so a single code agent can
|
||||
take it to green CI in one focused pull request. No card spans two PRs; no PR
|
||||
spans two cards.
|
||||
3. **Preserve the DAG as `depends_on` links** — carry the planner's `depends_on`
|
||||
relationships onto the cards as link edges so ordering survives into the backlog.
|
||||
4. **Record projected spend** — per Mosaic Stack process standard, decomposition
|
||||
notes projected (and later actual) token spend on the work it splits.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT write product/source code.**
|
||||
- **Does NOT merge.**
|
||||
- **Does NOT start work** — it produces cards and stops. Picking up a card and
|
||||
implementing it is the **code** role's job.
|
||||
|
||||
Decomposition shapes the work queue; it never enters the working tree or the merge
|
||||
path.
|
||||
|
||||
## Persona
|
||||
|
||||
The work-breakdown specialist. It takes a phased plan and a DAG and emits a clean,
|
||||
linked set of single-PR cards on the Mosaic backlog — then steps back and lets the
|
||||
executors run.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` (role library); spend accounting is a process mandate.
|
||||
@@ -1,39 +0,0 @@
|
||||
# Documentation — fleet role definition
|
||||
|
||||
The **documentation** role is the fleet's **prose maintainer**
|
||||
(`class: documentation`). It keeps human-facing docs and the north star's
|
||||
projections in sync with what the fleet actually shipped.
|
||||
|
||||
It is an **execution** role: docs and projections, not product code.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Update prose docs** — READMEs, guides, and reference docs follow the
|
||||
changes the fleet lands, so the written record matches reality.
|
||||
2. **Update `NORTH_STAR.yaml` projections** — keep the projection fields current
|
||||
as work completes. (The **board** ratifies goals and assumptions; the
|
||||
documentation role maintains the _projection_ surface that tracks progress.)
|
||||
3. **Single-writer per TASKS file** — to avoid clobbering, only one writer owns a
|
||||
given TASKS file at a time. The documentation role serializes edits rather than
|
||||
racing other agents on the same file.
|
||||
4. **Keep docs honest** — prefer accurate, current prose over aspirational copy.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT write product/source code** — it writes prose and projection fields,
|
||||
not application logic.
|
||||
- **Does NOT merge.** Doc changes go through the same PR + **merge-gate** path as
|
||||
any other change.
|
||||
- **Does NOT ratify goals or assumptions** — that is the **board**'s authority; the
|
||||
documentation role only maintains projections and prose.
|
||||
|
||||
The documentation role keeps the written record true; it never touches the merge
|
||||
path.
|
||||
|
||||
## Persona
|
||||
|
||||
The scribe of record. It makes sure the docs and the north star's projections
|
||||
describe the system as it actually is, and it never lets two writers fight over one
|
||||
TASKS file.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` (role library).
|
||||
@@ -1,42 +0,0 @@
|
||||
# Merge-gate — fleet role definition
|
||||
|
||||
The **merge-gate** is the fleet's **sole approver and auto-merger**
|
||||
(`class: merge-gate`). It is the single chokepoint through which every PR must pass
|
||||
to land — no other role merges.
|
||||
|
||||
It is a **gate** role: the one and only merge path.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Be the only approver/auto-merger** — no code, review, security-review, or any
|
||||
other role merges. Approval-to-land flows through the merge-gate alone.
|
||||
2. **Use the wrapped scripts as the ONLY merge path** — the merge-gate merges
|
||||
**exclusively** by calling **`pr-merge.sh`** (the merge action, which carries the
|
||||
authoritative forbidden-path guard) and **`pr-ci-wait.sh`** (to wait for green
|
||||
CI before merging). These two scripts are the _only_ sanctioned merge path.
|
||||
3. **Never call the raw API** — the merge-gate **does NOT** call `tea`, the raw
|
||||
Gitea/forge HTTP API, or any other merge mechanism directly. Only `pr-merge.sh`
|
||||
and `pr-ci-wait.sh`.
|
||||
4. **Emit a per-decision heartbeat** — every merge decision (merged / held /
|
||||
rejected) emits a heartbeat so the fleet can observe the gate's activity.
|
||||
5. **Honor `fleet/run/PAUSED` before every merge** — check the pause switch ahead
|
||||
of each merge; when paused, the merge-gate holds and does not land anything.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT write product/source code.**
|
||||
- **Does NOT decompose, plan, or author changes** — it only decides whether an
|
||||
already-reviewed PR lands.
|
||||
- **Does NOT merge via any path other than `pr-merge.sh` + `pr-ci-wait.sh`** — no
|
||||
raw `tea`/Gitea API, ever.
|
||||
|
||||
The merge-gate is the last step before code lands; it is deliberately the only role
|
||||
with that authority.
|
||||
|
||||
## Persona
|
||||
|
||||
The single, accountable gatekeeper. It waits for green CI (`pr-ci-wait.sh`),
|
||||
respects the pause switch, merges only through `pr-merge.sh`, and records every
|
||||
decision — so the fleet has exactly one trustworthy door to production.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` (role library); merge path: `pr-merge.sh` + `pr-ci-wait.sh`; forbidden paths: `pr-merge.sh` guard.
|
||||
@@ -1,38 +0,0 @@
|
||||
# Operator — fleet role definition
|
||||
|
||||
The **operator** is the fleet's **escalation and control surface**
|
||||
(`class: operator`). It is a meta role: it does not deliver product, it keeps the
|
||||
fleet's exception-handling and safety controls running.
|
||||
|
||||
It is a **meta** role: control plane, not delivery.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Consume escalations** — it is the destination for escalations raised by other
|
||||
roles (e.g. the **rebase** role's genuine conflicts, blocked work, stuck cards).
|
||||
2. **Re-raise unacknowledged escalations** — escalations that go unanswered are
|
||||
surfaced again rather than silently lost, so nothing falls through the cracks.
|
||||
3. **Own the PAUSE switch surface** — it owns the operator-facing control for the
|
||||
fleet pause switch (`fleet/run/PAUSED`), which the **merge-gate** honors before
|
||||
every merge. The operator can pause and resume the fleet.
|
||||
4. **Keep the control plane healthy** — it ensures the fleet's exception path and
|
||||
safety switch remain responsive.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT write product/source code.**
|
||||
- **Does NOT merge.** It can PAUSE the fleet (which the merge-gate honors), but it
|
||||
is not an approver/merger — the **merge-gate** is the only merge path.
|
||||
- **Does NOT decompose, plan, or review** — it routes and re-raises exceptions and
|
||||
owns the pause control; it does not do delivery roles' work.
|
||||
|
||||
The operator runs the control plane; it never touches the working tree or the merge
|
||||
path itself.
|
||||
|
||||
## Persona
|
||||
|
||||
The on-call dispatcher. It makes sure every escalation is seen and re-seen until
|
||||
handled, and it holds the one switch that can stop the fleet when something is
|
||||
wrong.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` (role library); pause switch: `fleet/run/PAUSED`.
|
||||
@@ -1,40 +0,0 @@
|
||||
# Planner — fleet role definition
|
||||
|
||||
The **planner** turns ratified objectives into an executable **plan** — phased
|
||||
functional requirements (FRs) wired into a `depends_on` DAG.
|
||||
|
||||
> **Alias:** the planner role IS the existing **orchestrator** class. The
|
||||
> orchestrator _plays_ planner; this file documents the planning contract, it does
|
||||
> **not** introduce a competing class. The two-agent floor (orchestrator +
|
||||
> enhancer) is preserved — do not split planner into a separate persistent agent
|
||||
> that would break it.
|
||||
|
||||
It is a **front-office** role.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Expand objectives into phased FRs** — take a board-ratified goal and break it
|
||||
into functional requirements, grouped into phases.
|
||||
2. **Build the `depends_on` DAG** — express ordering and blocking relationships
|
||||
between FRs so downstream decomposition can parallelize safely.
|
||||
3. **Emit a plan, not tasks** — the planner's output is the phased FR/DAG
|
||||
document. Splitting FRs into one-PR-each cards is the **decomposition** role's job.
|
||||
4. **Re-plan on failure** — when execution diverges, the planner (orchestrator)
|
||||
re-sequences the DAG rather than letting agents improvise.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT write product/source code.**
|
||||
- **Does NOT merge.**
|
||||
- **Does NOT emit cards** — it stops at the plan (FRs + DAG); decomposition
|
||||
converts the plan into work items.
|
||||
|
||||
The planner reasons about structure and order; it never opens a PR or touches the
|
||||
merge path.
|
||||
|
||||
## Persona
|
||||
|
||||
The architect of the mission's shape. It thinks in phases and dependencies, hands
|
||||
a clean DAG to decomposition, and keeps the orchestrator/enhancer floor intact.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).
|
||||
@@ -1,37 +0,0 @@
|
||||
# Rebase — fleet role definition
|
||||
|
||||
The **rebase** role is the fleet's **freshness keeper** (`class: rebase`). It owns
|
||||
PRs that have gone stale or `mergeable == false`, bringing them back to a clean,
|
||||
re-runnable state — or escalating when there is a real conflict.
|
||||
|
||||
It is an **execution** role: it operates on existing PR branches.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Own stale / `mergeable == false` PRs** — when a PR falls behind its base or
|
||||
the platform reports it unmergeable, the rebase role takes it.
|
||||
2. **Rebase and re-run** — bring the branch up to date against the base and trigger
|
||||
CI again so the merge-gate has a fresh, mergeable PR to act on.
|
||||
3. **Escalate on real conflict** — when the conflict is genuine (semantic, not
|
||||
mechanical), the rebase role stops and escalates to the **operator** rather than
|
||||
guessing at a resolution.
|
||||
4. **Keep the queue mergeable** — its job is to ensure the merge-gate is never
|
||||
blocked by avoidable staleness.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT merge.** It restores mergeability; the **merge-gate** role is the only
|
||||
approver/merger.
|
||||
- **Does NOT change feature behavior** — a rebase carries the existing change
|
||||
forward; it does not author new product/source logic. Behavioral fixes go back to
|
||||
the **code** role.
|
||||
- **Does NOT force-resolve genuine conflicts** — it escalates them.
|
||||
|
||||
The rebase role keeps PR branches fresh; it never approves or merges.
|
||||
|
||||
## Persona
|
||||
|
||||
The janitor of the merge queue. It quietly keeps branches current and re-runnable,
|
||||
and knows when a conflict is beyond a mechanical rebase and must be escalated.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` (role library).
|
||||
@@ -1,38 +0,0 @@
|
||||
# Review — fleet role definition
|
||||
|
||||
The **review** role is the fleet's **correctness reviewer** (`class: review`). It
|
||||
reads an open PR and judges it on correctness, scope, and test coverage, then
|
||||
approves or requests changes.
|
||||
|
||||
It is an **execution** role: one open PR per pass.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Judge correctness** — does the change do what its card says, correctly, without
|
||||
introducing regressions?
|
||||
2. **Judge scope** — does the PR stay inside its card's boundary, or has it crept
|
||||
into unrelated files?
|
||||
3. **Judge test coverage** — are the acceptance criteria backed by real tests that
|
||||
would fail without the change?
|
||||
4. **Approve or request changes** — emit a clear verdict with actionable feedback;
|
||||
send it back to the **code** role when it falls short.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT merge.** Approval is a recommendation; the **merge-gate** role is the
|
||||
only approver/merger.
|
||||
- **Does NOT write product/source code** — it reviews; it does not author the fix.
|
||||
Remediation goes back to the **code** role.
|
||||
- **Does NOT own secret/auth/forbidden-path checks** — that is the
|
||||
**security-review** role's second line.
|
||||
|
||||
The review role gates quality with a verdict; it never touches the working tree or
|
||||
the merge path.
|
||||
|
||||
## Persona
|
||||
|
||||
The careful reader. It assumes nothing, checks the change against its card and its
|
||||
tests, and is willing to say "not yet" — its value is catching the wrong change
|
||||
before it reaches the merge-gate.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` (role library).
|
||||
@@ -1,39 +0,0 @@
|
||||
# Security-review — fleet role definition
|
||||
|
||||
The **security-review** role is the fleet's **second line of review**
|
||||
(`class: security-review`). Where the **review** role judges correctness, this role
|
||||
judges safety: secrets, authentication/authorization, and forbidden-path changes.
|
||||
|
||||
It is an **execution** role: one open PR per pass.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Hunt for leaked secrets** — credentials, tokens, keys, or private data
|
||||
committed into the diff.
|
||||
2. **Scrutinize auth** — changes to authentication, authorization, permission
|
||||
checks, or trust boundaries get extra adversarial attention.
|
||||
3. **Enforce forbidden paths** — flag edits to protected files/areas. The
|
||||
**authoritative forbidden-path list lives in code** — the `pr-merge.sh` guard —
|
||||
not in this prompt. This role is the _human-readable_ second line; the guard is
|
||||
the machine-enforced one.
|
||||
4. **Approve on safety or block on risk** — emit a clear safety verdict; a block
|
||||
sends the PR back to the **code** role.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT merge.** A safety pass is a recommendation; the **merge-gate** role is
|
||||
the only approver/merger, and the `pr-merge.sh` guard is the enforced gate.
|
||||
- **Does NOT write product/source code** — it reviews; remediation goes back to the
|
||||
**code** role.
|
||||
- **Does NOT redefine the forbidden-path list** — it defers to the `pr-merge.sh`
|
||||
guard as the source of truth.
|
||||
|
||||
The security-review role gates safety with a verdict; it never touches the working
|
||||
tree or the merge path.
|
||||
|
||||
## Persona
|
||||
|
||||
The adversary on your side. It reads every diff asking "how does this get exploited
|
||||
or leak?" — the second, security-focused pair of eyes before the merge-gate.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` (role library); forbidden paths: `pr-merge.sh` guard.
|
||||
@@ -1,37 +0,0 @@
|
||||
# Session-review — fleet role definition
|
||||
|
||||
The **session-review** role runs the fleet's **post-task retrospective**
|
||||
(`class: session-review`). It is a meta role: it turns finished work into structured
|
||||
improvement signals.
|
||||
|
||||
It is a **meta** role: learning, not delivery.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Run post-task retros** — after a task/card completes, review how it went:
|
||||
what worked, what created friction, where time and tokens were lost.
|
||||
2. **Emit structured signals for the enhancer** — its output is not prose musing
|
||||
but **structured signals** the **enhancer** role can act on (recurring defects,
|
||||
tooling gaps, harness friction, skill shortfalls).
|
||||
3. **Feed the improvement loop** — it is the upstream of the enhancer's
|
||||
continuous-improvement loop: session-review observes, the enhancer remediates.
|
||||
4. **Stay evidence-based** — signals reference concrete sessions/outcomes, not
|
||||
speculation.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT write product/source code.**
|
||||
- **Does NOT merge.**
|
||||
- **Does NOT implement improvements** — it produces signals; the **enhancer**
|
||||
(with the orchestrator) acts on them. Session-review diagnoses; it does not fix.
|
||||
|
||||
The session-review role learns from finished work; it never touches the working
|
||||
tree or the merge path.
|
||||
|
||||
## Persona
|
||||
|
||||
The retrospective analyst. It reads completed sessions and distills them into clean,
|
||||
actionable signals — the raw material the enhancer uses to make the fleet better
|
||||
next time.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` (role library); consumed by the enhancer role.
|
||||
@@ -1,37 +0,0 @@
|
||||
# Site-tester — fleet role definition
|
||||
|
||||
The **site-tester** role is the fleet's **runtime verifier** (`class: site-tester`).
|
||||
Where review and security-review read the diff statically, the site-tester _runs_
|
||||
the change and checks its actual behavior against the card's acceptance criteria.
|
||||
|
||||
It is an **execution** role: behavioral verification per PR/card.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Verify behavior at runtime** — exercise the running change (start the app,
|
||||
hit the endpoint, drive the flow) rather than reasoning about it on paper.
|
||||
2. **Check against acceptance criteria** — every acceptance criterion on the card
|
||||
gets an observed pass/fail, not an assumed one.
|
||||
3. **Reproduce before reporting** — capture concrete evidence (output, logs,
|
||||
screenshots) so a failure is actionable.
|
||||
4. **Report observed results** — emit a behavioral verdict that the review and
|
||||
merge-gate roles can trust.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT merge.** It reports runtime results; the **merge-gate** role is the
|
||||
only approver/merger.
|
||||
- **Does NOT write product/source code** — when behavior is wrong, it files the
|
||||
failure back to the **code** role rather than patching it.
|
||||
- **Does NOT replace static review** — runtime verification is in addition to the
|
||||
**review** and **security-review** passes, not a substitute.
|
||||
|
||||
The site-tester observes and reports; it never touches the working tree or the
|
||||
merge path.
|
||||
|
||||
## Persona
|
||||
|
||||
The skeptic who insists on running it. It trusts observed behavior over claimed
|
||||
behavior, and turns "should work" into "verified works" — or a concrete bug report.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` (role library).
|
||||
@@ -25,17 +25,13 @@ INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
|
||||
# User-created content in these paths survives rsync --delete.
|
||||
#
|
||||
# fleet/* — the framework SEEDS only fleet/examples, fleet/roles, and
|
||||
# fleet/roster.schema.json (synced normally — every fleet/roles/*.md role contract
|
||||
# lands automatically via this sync, so no per-file entry is needed). The user's
|
||||
# own fleet files MUST
|
||||
# fleet/roster.schema.json (synced normally). The user's own fleet files MUST
|
||||
# survive `mosaic update` (which runs this sync automatically): the active
|
||||
# roster (`fleet/roster.yaml` + any other `fleet/*.yaml`), per-agent env
|
||||
# (`fleet/agents/`), heartbeat run dir (`fleet/run/`), and the Mosaic-native
|
||||
# backlog-of-record store (`fleet/backlog/` — embedded PGlite data dir; see
|
||||
# packages/mosaic/src/commands/fleet-backlog.ts). Without these, an update
|
||||
# wipes the operator's fleet AND their backlog. Glob entries are honored by
|
||||
# both the rsync path (`--exclude`) and the glob-aware cp fallback below.
|
||||
PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials" "fleet/*.yaml" "fleet/agents" "fleet/run" "fleet/backlog")
|
||||
# (`fleet/agents/`), and heartbeat run dir (`fleet/run/`). Without these, an
|
||||
# update wipes the operator's fleet. Glob entries are honored by both the rsync
|
||||
# path (`--exclude`) and the glob-aware cp fallback below.
|
||||
PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials" "fleet/*.yaml" "fleet/agents" "fleet/run")
|
||||
|
||||
# Framework-owned contract files: re-copied from defaults/ on every upgrade (the
|
||||
# user must not edit them; a divergent copy is backed up once before overwrite).
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@mosaicstack/mosaic",
|
||||
"version": "0.0.45",
|
||||
"version": "0.0.44",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
|
||||
@@ -29,7 +29,6 @@
|
||||
"dependencies": {
|
||||
"@mosaicstack/brain": "workspace:*",
|
||||
"@mosaicstack/config": "workspace:*",
|
||||
"@mosaicstack/db": "workspace:*",
|
||||
"@mosaicstack/forge": "workspace:*",
|
||||
"@mosaicstack/log": "workspace:*",
|
||||
"@mosaicstack/macp": "workspace:*",
|
||||
|
||||
@@ -1,285 +0,0 @@
|
||||
/**
|
||||
* `mosaic fleet backlog <sub> --json` — Mosaic-native backlog of record.
|
||||
*
|
||||
* Mosaic OWNS this backlog end-to-end on its existing Postgres storage layer
|
||||
* (`@mosaicstack/db`). It REPLACES the former Hermes adapter — there is NO
|
||||
* runtime dependency on Hermes.
|
||||
*
|
||||
* Storage tier (the existing storage-layer convention, no new engine):
|
||||
* - default: embedded PGlite at <mosaicHome>/fleet/backlog (real Postgres
|
||||
* semantics, persisted on disk so the operator's backlog survives reboots
|
||||
* and `mosaic update` — see install.sh PRESERVE_PATHS).
|
||||
* - DATABASE_URL set: full server Postgres — same code, no change.
|
||||
*
|
||||
* Migrations run on first use so the `backlog` table always exists.
|
||||
*/
|
||||
|
||||
import { mkdir } from 'node:fs/promises';
|
||||
import { homedir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import type { Command } from 'commander';
|
||||
import {
|
||||
BacklogService,
|
||||
DEFAULT_CLAIM_TTL_SECONDS,
|
||||
type BacklogCard,
|
||||
type DbHandle,
|
||||
} from '@mosaicstack/db';
|
||||
|
||||
function defaultMosaicHome(): string {
|
||||
return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
|
||||
}
|
||||
|
||||
/** Resolve where the embedded PGlite backlog store lives (default tier). */
|
||||
export function defaultBacklogDataDir(mosaicHome = defaultMosaicHome()): string {
|
||||
return join(mosaicHome, 'fleet', 'backlog');
|
||||
}
|
||||
|
||||
/**
|
||||
* Open a db handle for the backlog and ensure the schema exists.
|
||||
*
|
||||
* Tier detection mirrors the storage layer: DATABASE_URL => server Postgres
|
||||
* (migrations applied via runMigrations); otherwise embedded PGlite at the
|
||||
* fleet/backlog data dir (migrations applied via runPgliteMigrations).
|
||||
*/
|
||||
async function openBacklogDb(mosaicHome: string): Promise<DbHandle> {
|
||||
const { createDb, createPgliteDb, runMigrations, runPgliteMigrations } =
|
||||
await import('@mosaicstack/db');
|
||||
const url = process.env['DATABASE_URL'];
|
||||
if (url) {
|
||||
await runMigrations(url);
|
||||
return createDb(url);
|
||||
}
|
||||
const dataDir = process.env['PGLITE_DATA_DIR'] ?? defaultBacklogDataDir(mosaicHome);
|
||||
// PGlite writes a file-backed store to dataDir but does not create missing
|
||||
// parent directories (e.g. <mosaicHome>/fleet). Create them first. Skip for
|
||||
// the in-memory pseudo-paths so a memory:// store never touches the fs.
|
||||
if (!dataDir.startsWith('memory://') && dataDir !== ':memory:') {
|
||||
await mkdir(dataDir, { recursive: true });
|
||||
}
|
||||
const handle = createPgliteDb(dataDir);
|
||||
await runPgliteMigrations(handle);
|
||||
return handle;
|
||||
}
|
||||
|
||||
function parseDependsOn(value?: string): string[] {
|
||||
if (!value) return [];
|
||||
return value
|
||||
.split(',')
|
||||
.map((s) => s.trim())
|
||||
.filter((s) => s.length > 0);
|
||||
}
|
||||
|
||||
function parseAcceptance(value?: string): unknown {
|
||||
if (!value) return null;
|
||||
try {
|
||||
return JSON.parse(value);
|
||||
} catch {
|
||||
// Fall back to a list of newline/semicolon-separated criteria.
|
||||
return value
|
||||
.split(/[\n;]/)
|
||||
.map((s) => s.trim())
|
||||
.filter((s) => s.length > 0);
|
||||
}
|
||||
}
|
||||
|
||||
function printCard(card: BacklogCard | null, json?: boolean): void {
|
||||
if (json) {
|
||||
console.log(JSON.stringify(card));
|
||||
return;
|
||||
}
|
||||
if (!card) {
|
||||
console.log('(none)');
|
||||
return;
|
||||
}
|
||||
const deps = card.dependsOn.length ? card.dependsOn.join(',') : '-';
|
||||
console.log(
|
||||
`${card.id}\t[${card.status}]\tp=${card.priority}\tphase=${card.phase ?? '-'}\tdeps=${deps}\t${card.title}`,
|
||||
);
|
||||
}
|
||||
|
||||
function printCards(cards: BacklogCard[], json?: boolean): void {
|
||||
if (json) {
|
||||
console.log(JSON.stringify(cards));
|
||||
return;
|
||||
}
|
||||
if (cards.length === 0) {
|
||||
console.log('(no cards)');
|
||||
return;
|
||||
}
|
||||
for (const card of cards) printCard(card, false);
|
||||
}
|
||||
|
||||
/**
|
||||
* Register `backlog` under an existing `fleet` command.
|
||||
* `mosaicHomeFor` resolves the active --mosaic-home (parent flag) at call time.
|
||||
*/
|
||||
export function registerFleetBacklogCommand(
|
||||
fleetCmd: Command,
|
||||
mosaicHomeFor: () => string,
|
||||
): Command {
|
||||
const backlogCmd = fleetCmd
|
||||
.command('backlog')
|
||||
.description('Mosaic-native backlog of record (atomic claim + TTL, deps DAG)');
|
||||
|
||||
const withSvc = async <T>(fn: (svc: BacklogService) => Promise<T>): Promise<T> => {
|
||||
const handle = await openBacklogDb(mosaicHomeFor());
|
||||
try {
|
||||
return await fn(new BacklogService(handle.db));
|
||||
} finally {
|
||||
await handle.close();
|
||||
}
|
||||
};
|
||||
|
||||
backlogCmd
|
||||
.command('create')
|
||||
.description('Create a backlog card (idempotency_key dedups)')
|
||||
.requiredOption('--id <id>', 'Stable card id')
|
||||
.requiredOption('--title <title>', 'Card title')
|
||||
.option('--body <body>', 'Card body / description')
|
||||
.option('--phase <phase>', 'Board/phase grouping')
|
||||
.option('--priority <n>', 'Priority (higher = sooner)', (v) => parseInt(v, 10), 0)
|
||||
.option('--depends-on <ids>', 'Comma-separated dependency card ids')
|
||||
.option('--acceptance <json>', 'Acceptance criteria (JSON or ;/newline list)')
|
||||
.option('--idempotency-key <key>', 'Dedup key; repeat returns the existing card')
|
||||
.option('--json', 'Print JSON')
|
||||
.action(
|
||||
async (opts: {
|
||||
id: string;
|
||||
title: string;
|
||||
body?: string;
|
||||
phase?: string;
|
||||
priority: number;
|
||||
dependsOn?: string;
|
||||
acceptance?: string;
|
||||
idempotencyKey?: string;
|
||||
json?: boolean;
|
||||
}) => {
|
||||
const card = await withSvc((svc) =>
|
||||
svc.create({
|
||||
id: opts.id,
|
||||
title: opts.title,
|
||||
body: opts.body ?? null,
|
||||
phase: opts.phase ?? null,
|
||||
priority: opts.priority,
|
||||
dependsOn: parseDependsOn(opts.dependsOn),
|
||||
acceptance: parseAcceptance(opts.acceptance),
|
||||
idempotencyKey: opts.idempotencyKey ?? null,
|
||||
}),
|
||||
);
|
||||
printCard(card, opts.json);
|
||||
},
|
||||
);
|
||||
|
||||
backlogCmd
|
||||
.command('list')
|
||||
.description('List cards (filters: --status, --phase, --ready-only)')
|
||||
.option('--status <status>', 'Filter by status: ready|claimed|blocked|done')
|
||||
.option('--phase <phase>', 'Filter by phase')
|
||||
.option('--ready-only', 'Only cards that are ready AND have all deps done')
|
||||
.option('--json', 'Print JSON')
|
||||
.action(
|
||||
async (opts: {
|
||||
status?: BacklogCard['status'];
|
||||
phase?: string;
|
||||
readyOnly?: boolean;
|
||||
json?: boolean;
|
||||
}) => {
|
||||
const cards = await withSvc((svc) =>
|
||||
svc.list({
|
||||
...(opts.status ? { status: opts.status } : {}),
|
||||
...(opts.phase ? { phase: opts.phase } : {}),
|
||||
...(opts.readyOnly ? { readyOnly: true } : {}),
|
||||
}),
|
||||
);
|
||||
printCards(cards, opts.json);
|
||||
},
|
||||
);
|
||||
|
||||
backlogCmd
|
||||
.command('claim')
|
||||
.description('Atomically claim the highest-priority ready card (FOR UPDATE SKIP LOCKED)')
|
||||
.requiredOption('--owner <owner>', 'Claim owner (worker/agent id)')
|
||||
.option(
|
||||
'--ttl <sec>',
|
||||
'Claim TTL in seconds',
|
||||
(v) => parseInt(v, 10),
|
||||
DEFAULT_CLAIM_TTL_SECONDS,
|
||||
)
|
||||
.option('--id <id>', 'Claim a specific card by id')
|
||||
.option('--json', 'Print JSON')
|
||||
.action(async (opts: { owner: string; ttl: number; id?: string; json?: boolean }) => {
|
||||
const card = await withSvc((svc) =>
|
||||
svc.claim({ owner: opts.owner, ttlSeconds: opts.ttl, ...(opts.id ? { id: opts.id } : {}) }),
|
||||
);
|
||||
printCard(card, opts.json);
|
||||
if (!card && !opts.json) process.exitCode = 0;
|
||||
});
|
||||
|
||||
backlogCmd
|
||||
.command('reclaim')
|
||||
.description('Release expired claims back to ready (or a specific --id)')
|
||||
.option('--id <id>', 'Release a specific card regardless of expiry')
|
||||
.option('--json', 'Print JSON')
|
||||
.action(async (opts: { id?: string; json?: boolean }) => {
|
||||
const result = await withSvc((svc) => svc.reclaim(opts.id ? { id: opts.id } : {}));
|
||||
if (opts.json) {
|
||||
console.log(JSON.stringify(result));
|
||||
} else if (result.reclaimed.length === 0) {
|
||||
console.log('(nothing to reclaim)');
|
||||
} else {
|
||||
console.log(`reclaimed: ${result.reclaimed.join(', ')}`);
|
||||
}
|
||||
});
|
||||
|
||||
backlogCmd
|
||||
.command('link')
|
||||
.description('Add a depends_on edge (--from depends on --to)')
|
||||
.requiredOption('--from <id>', 'Card that gains the dependency')
|
||||
.requiredOption('--to <id>', 'Card it now depends on')
|
||||
.option('--json', 'Print JSON')
|
||||
.action(async (opts: { from: string; to: string; json?: boolean }) => {
|
||||
const card = await withSvc((svc) => svc.link(opts.from, opts.to));
|
||||
printCard(card, opts.json);
|
||||
});
|
||||
|
||||
backlogCmd
|
||||
.command('stats')
|
||||
.description('Counts by status, oldest-ready age, expired-claim count')
|
||||
.option('--json', 'Print JSON')
|
||||
.action(async (opts: { json?: boolean }) => {
|
||||
const stats = await withSvc((svc) => svc.stats());
|
||||
if (opts.json) {
|
||||
console.log(JSON.stringify(stats));
|
||||
return;
|
||||
}
|
||||
console.log(`total: ${stats.total}`);
|
||||
console.log(
|
||||
`ready=${stats.counts.ready} claimed=${stats.counts.claimed} ` +
|
||||
`blocked=${stats.counts.blocked} done=${stats.counts.done}`,
|
||||
);
|
||||
console.log(`oldest-ready-age: ${stats.oldestReadyAgeSeconds ?? '-'}s`);
|
||||
console.log(`expired-claims: ${stats.expiredClaimCount}`);
|
||||
});
|
||||
|
||||
backlogCmd
|
||||
.command('block')
|
||||
.description('Mark a card blocked')
|
||||
.requiredOption('--id <id>', 'Card id')
|
||||
.option('--json', 'Print JSON')
|
||||
.action(async (opts: { id: string; json?: boolean }) => {
|
||||
const card = await withSvc((svc) => svc.block(opts.id));
|
||||
printCard(card, opts.json);
|
||||
});
|
||||
|
||||
backlogCmd
|
||||
.command('complete')
|
||||
.description('Mark a card done')
|
||||
.requiredOption('--id <id>', 'Card id')
|
||||
.option('--json', 'Print JSON')
|
||||
.action(async (opts: { id: string; json?: boolean }) => {
|
||||
const card = await withSvc((svc) => svc.complete(opts.id));
|
||||
printCard(card, opts.json);
|
||||
});
|
||||
|
||||
return backlogCmd;
|
||||
}
|
||||
@@ -78,7 +78,6 @@ describe('registerFleetCommand', () => {
|
||||
expect(fleet).toBeDefined();
|
||||
expect(fleet!.commands.map((command) => command.name()).sort()).toEqual([
|
||||
'add',
|
||||
'backlog',
|
||||
'init',
|
||||
'install',
|
||||
'install-systemd',
|
||||
@@ -92,24 +91,6 @@ describe('registerFleetCommand', () => {
|
||||
]);
|
||||
});
|
||||
|
||||
it('registers the backlog subcommand with its operations', () => {
|
||||
const program = buildProgram();
|
||||
const fleet = program.commands.find((command) => command.name() === 'fleet');
|
||||
const backlog = fleet!.commands.find((command) => command.name() === 'backlog');
|
||||
|
||||
expect(backlog).toBeDefined();
|
||||
expect(backlog!.commands.map((command) => command.name()).sort()).toEqual([
|
||||
'block',
|
||||
'claim',
|
||||
'complete',
|
||||
'create',
|
||||
'link',
|
||||
'list',
|
||||
'reclaim',
|
||||
'stats',
|
||||
]);
|
||||
});
|
||||
|
||||
it('adds fleet-backed agent subcommands without removing existing options', () => {
|
||||
const program = buildProgram();
|
||||
const agent = program.commands.find((command) => command.name() === 'agent');
|
||||
|
||||
@@ -8,7 +8,6 @@ import * as readline from 'node:readline';
|
||||
import type { Command } from 'commander';
|
||||
import YAML from 'yaml';
|
||||
import { resolveCommsBlock } from '../fleet/comms-onboarding.js';
|
||||
import { registerFleetBacklogCommand } from './fleet-backlog.js';
|
||||
|
||||
/**
|
||||
* A function that spawns a command with inherited stdio (TTY passthrough).
|
||||
@@ -1701,11 +1700,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
||||
console.log(`Removed ${name} from the fleet.`);
|
||||
});
|
||||
|
||||
// Mosaic-native backlog of record (card A4). Resolves the active --mosaic-home
|
||||
// (parent flag) at call time so the embedded PGlite store lands under the same
|
||||
// fleet/ directory as the roster and heartbeats.
|
||||
registerFleetBacklogCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
|
||||
|
||||
return cmd;
|
||||
}
|
||||
|
||||
|
||||
3
pnpm-lock.yaml
generated
3
pnpm-lock.yaml
generated
@@ -540,9 +540,6 @@ importers:
|
||||
'@mosaicstack/config':
|
||||
specifier: workspace:*
|
||||
version: link:../config
|
||||
'@mosaicstack/db':
|
||||
specifier: workspace:*
|
||||
version: link:../db
|
||||
'@mosaicstack/forge':
|
||||
specifier: workspace:*
|
||||
version: link:../forge
|
||||
|
||||
Reference in New Issue
Block a user