attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/database/service/processService.js

@@ -0,0 +1,45 @@
+import { ProcessRepository } from "../repository/processRepository.js";
+import { createProcess, getProcess, listProcesses, terminateProcess, transitionProcess } from "../../process/process.js";
+import { Service } from "./service.js";
+/**
+ * One service per entity: `processes`.
+ */
+export class ProcessService extends Service {
+    db;
+    constructor(db, processes) {
+        super(processes, "Process");
+        this.db = db;
+    }
+    byId(pid) {
+        return this.findById(pid);
+    }
+    byPublicId(id) {
+        return this.repository.byPublicId(id);
+    }
+    byState(state, limit = 100) {
+        return this.repository.byState(state, limit);
+    }
+    runnable(limit = 100) {
+        return this.repository.runnable(limit);
+    }
+    create(spec, at) {
+        const record = createProcess(this.db, spec, at);
+        const row = this.byId(record.pid);
+        if (row === (void 0)) {
+            throw new Error(`process ${record.pid} was not stored`);
+        }
+        return row;
+    }
+    record(pid) {
+        return getProcess(this.db, pid);
+    }
+    list(state) {
+        return listProcesses(this.db, state);
+    }
+    transition(pid, from, to, patch = {}) {
+        return transitionProcess(this.db, pid, from, to, patch);
+    }
+    terminate(pid, note, at, code = "TERMINATED") {
+        return terminateProcess(this.db, pid, note, at, code);
+    }
+}

package/lib/database/service/registryServices.d.ts

@@ -0,0 +1,43 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { PrimaryKey } from "../entity/entity.js";
+import type { AttestationEntity, ConceptEntity, ModuleEntity } from "../entity/registry.js";
+import { AttestationRepository, ConceptRepository, ModuleRepository } from "../repository/registryRepository.js";
+import { Service } from "./service.js";
+/**
+ * Concept link returned with a module.
+ */
+export interface ModuleConceptLink {
+    cid: number;
+    id: string;
+    role: string;
+}
+/**
+ * One service per entity: `concepts` in the registry.
+ */
+export declare class ConceptService extends Service<ConceptEntity, PrimaryKey, ConceptRepository> {
+    private readonly db;
+    constructor(db: DatabaseSync, concepts: ConceptRepository);
+    byId(cid: number): ConceptEntity | undefined;
+    byPublicId(id: string): ConceptEntity | undefined;
+    list(status?: string): ConceptEntity[];
+    get connection(): DatabaseSync;
+}
+/**
+ * One service per entity: `modules` in the registry.
+ */
+export declare class ModuleService extends Service<ModuleEntity, PrimaryKey, ModuleRepository> {
+    private readonly db;
+    constructor(db: DatabaseSync, modules: ModuleRepository);
+    byId(mid: number): ModuleEntity | undefined;
+    byPublicId(id: string): ModuleEntity | undefined;
+    list(kind?: string): ModuleEntity[];
+    concepts(mid: number): ModuleConceptLink[];
+    get connection(): DatabaseSync;
+}
+/**
+ * One service per entity: `attestations` (evidence links for registry rows).
+ */
+export declare class AttestationService extends Service<AttestationEntity, PrimaryKey, AttestationRepository> {
+    constructor(attestations: AttestationRepository);
+    forSubject(subjectKind: string, subjectId: string): AttestationEntity[];
+}

package/lib/database/service/registryServices.js

@@ -0,0 +1,60 @@
+import { AttestationRepository, ConceptRepository, ModuleRepository } from "../repository/registryRepository.js";
+import { Service } from "./service.js";
+/**
+ * One service per entity: `concepts` in the registry.
+ */
+export class ConceptService extends Service {
+    db;
+    constructor(db, concepts) {
+        super(concepts, "Concept");
+        this.db = db;
+    }
+    byId(cid) {
+        return this.findById(cid);
+    }
+    byPublicId(id) {
+        return this.repository.byPublicId(id);
+    }
+    list(status) {
+        return status === (void 0) ? this.repository.all() : this.repository.byStatus(status);
+    }
+    get connection() {
+        return this.db;
+    }
+}
+/**
+ * One service per entity: `modules` in the registry.
+ */
+export class ModuleService extends Service {
+    db;
+    constructor(db, modules) {
+        super(modules, "Module");
+        this.db = db;
+    }
+    byId(mid) {
+        return this.findById(mid);
+    }
+    byPublicId(id) {
+        return this.repository.byPublicId(id);
+    }
+    list(kind) {
+        return kind === (void 0) ? this.repository.all() : this.repository.byKind(kind);
+    }
+    concepts(mid) {
+        return this.repository.concepts(mid);
+    }
+    get connection() {
+        return this.db;
+    }
+}
+/**
+ * One service per entity: `attestations` (evidence links for registry rows).
+ */
+export class AttestationService extends Service {
+    constructor(attestations) {
+        super(attestations, "Attestation");
+    }
+    forSubject(subjectKind, subjectId) {
+        return this.repository.forSubject(subjectKind, subjectId);
+    }
+}

package/lib/database/service/service.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Service abstraction over one repository.
+ *
+ * Services own use-case policy: they translate application input into
+ * repository operations, return domain-shaped rows, and turn a missing row
+ * into a stable error. They never import `node:sqlite` or construct SQL.
+ *
+ * @typeParam TEntity - Row shape returned by the service.
+ * @typeParam TKey - Primary-key type.
+ * @typeParam TRepository - Concrete repository used by the service.
+ */
+import type { PrimaryKey } from "../entity/entity.js";
+import type { Page, Query, Repository } from "../repository/repository.js";
+import type { MutationResult, SqlParameter } from "../sql/sql.js";
+/**
+ * Error raised when a service requires a row that does not exist.
+ */
+export declare class EntityNotFoundError extends Error {
+    /**
+     * Entity label used in the message.
+     */
+    readonly entityName: string;
+    /**
+     * Missing primary-key value.
+     */
+    readonly id: PrimaryKey;
+    constructor(entityName: string, id: PrimaryKey);
+}
+export declare abstract class Service<TEntity extends object, TKey extends PrimaryKey = PrimaryKey, TRepository extends Repository<TEntity, TKey> = Repository<TEntity, TKey>> {
+    protected readonly repository: TRepository;
+    protected readonly entityName: string;
+    /**
+     * Create a service.
+     *
+     * @param repository - Repository used for all persistence.
+     * @param entityName - Label used in missing-row errors.
+     */
+    protected constructor(repository: TRepository, entityName?: string);
+    /**
+     * Find one row by primary key.
+     *
+     * @param id - Primary-key value.
+     * @returns The row, or `undefined`.
+     */
+    findById(id: TKey): TEntity | undefined;
+    /**
+     * Find one row or throw.
+     *
+     * @param id - Primary-key value.
+     * @param entityName - Optional label override.
+     * @returns The row.
+     * @throws EntityNotFoundError when the row is absent.
+     */
+    requireById(id: TKey, entityName?: string): TEntity;
+    /**
+     * Read rows in unspecified order.
+     *
+     * @param limit - Maximum row count.
+     * @returns Matching rows.
+     */
+    all(limit?: number): TEntity[];
+    /**
+     * Read rows with a typed query descriptor.
+     *
+     * @param query - Filter, ordering and pagination options.
+     * @returns Matching rows.
+     */
+    findAll(query: Query<TEntity>): TEntity[];
+    /**
+     * Read one page of rows.
+     *
+     * @param query - Filter and ordering options.
+     * @param pageNumber - Zero-based page index.
+     * @param pageSize - Requested page size.
+     * @returns A page descriptor.
+     */
+    page(query: Query<TEntity>, pageNumber?: number, pageSize?: number): Page<TEntity>;
+    /**
+     * Read rows with a trusted WHERE fragment.
+     *
+     * @param clause - SQL after `WHERE`.
+     * @param params - Bound values.
+     * @returns Matching rows.
+     */
+    where(clause: string, ...params: SqlParameter[]): TEntity[];
+    /**
+     * Count rows.
+     *
+     * @param clause - Optional SQL after `WHERE`.
+     * @param params - Bound values.
+     * @returns Number of rows.
+     */
+    count(clause?: string, ...params: SqlParameter[]): number;
+    /**
+     * Test whether a row exists.
+     *
+     * @param id - Primary-key value.
+     * @returns `true` when present.
+     */
+    exists(id: TKey): boolean;
+    /**
+     * Insert one row.
+     *
+     * @param values - Column values.
+     * @returns Mutation metadata.
+     */
+    insert(values: Readonly<Record<string, unknown>>): MutationResult;
+    /**
+     * Update one row by primary key.
+     *
+     * @param id - Primary-key value.
+     * @param values - Column values.
+     * @returns Number of changed rows.
+     */
+    update(id: TKey, values: Readonly<Record<string, unknown>>): number;
+    /**
+     * Delete one row by primary key.
+     *
+     * @param id - Primary-key value.
+     * @returns Number of deleted rows.
+     */
+    delete(id: TKey): number;
+    /**
+     * Insert or update according to unique columns.
+     *
+     * @param values - Column values.
+     * @param conflictColumns - Unique columns; defaults to the primary key.
+     * @returns Mutation metadata.
+     */
+    upsert(values: Readonly<Record<string, unknown>>, conflictColumns?: readonly string[]): MutationResult;
+}

package/lib/database/service/service.js

@@ -0,0 +1,153 @@
+/**
+ * Error raised when a service requires a row that does not exist.
+ */
+export class EntityNotFoundError extends Error {
+    /**
+     * Entity label used in the message.
+     */
+    entityName;
+    /**
+     * Missing primary-key value.
+     */
+    id;
+    constructor(entityName, id) {
+        super(`${entityName} not found: ${id}`);
+        this.name = "EntityNotFoundError";
+        this.entityName = entityName;
+        this.id = id;
+    }
+}
+export class Service {
+    repository;
+    entityName;
+    /**
+     * Create a service.
+     *
+     * @param repository - Repository used for all persistence.
+     * @param entityName - Label used in missing-row errors.
+     */
+    constructor(repository, entityName = "entity") {
+        this.repository = repository;
+        this.entityName = entityName;
+    }
+    /**
+     * Find one row by primary key.
+     *
+     * @param id - Primary-key value.
+     * @returns The row, or `undefined`.
+     */
+    findById(id) {
+        return this.repository.findById(id);
+    }
+    /**
+     * Find one row or throw.
+     *
+     * @param id - Primary-key value.
+     * @param entityName - Optional label override.
+     * @returns The row.
+     * @throws EntityNotFoundError when the row is absent.
+     */
+    requireById(id, entityName = this.entityName) {
+        const row = this.repository.findById(id);
+        if (row === (void 0)) {
+            throw new EntityNotFoundError(entityName, id);
+        }
+        return row;
+    }
+    /**
+     * Read rows in unspecified order.
+     *
+     * @param limit - Maximum row count.
+     * @returns Matching rows.
+     */
+    all(limit = 1000) {
+        return this.repository.all(limit);
+    }
+    /**
+     * Read rows with a typed query descriptor.
+     *
+     * @param query - Filter, ordering and pagination options.
+     * @returns Matching rows.
+     */
+    findAll(query) {
+        return this.repository.findAll(query);
+    }
+    /**
+     * Read one page of rows.
+     *
+     * @param query - Filter and ordering options.
+     * @param pageNumber - Zero-based page index.
+     * @param pageSize - Requested page size.
+     * @returns A page descriptor.
+     */
+    page(query, pageNumber = 0, pageSize = 20) {
+        return this.repository.page(query, pageNumber, pageSize);
+    }
+    /**
+     * Read rows with a trusted WHERE fragment.
+     *
+     * @param clause - SQL after `WHERE`.
+     * @param params - Bound values.
+     * @returns Matching rows.
+     */
+    where(clause, ...params) {
+        return this.repository.where(clause, ...params);
+    }
+    /**
+     * Count rows.
+     *
+     * @param clause - Optional SQL after `WHERE`.
+     * @param params - Bound values.
+     * @returns Number of rows.
+     */
+    count(clause, ...params) {
+        return this.repository.count(clause, ...params);
+    }
+    /**
+     * Test whether a row exists.
+     *
+     * @param id - Primary-key value.
+     * @returns `true` when present.
+     */
+    exists(id) {
+        return this.repository.exists(id);
+    }
+    /**
+     * Insert one row.
+     *
+     * @param values - Column values.
+     * @returns Mutation metadata.
+     */
+    insert(values) {
+        return this.repository.insert(values);
+    }
+    /**
+     * Update one row by primary key.
+     *
+     * @param id - Primary-key value.
+     * @param values - Column values.
+     * @returns Number of changed rows.
+     */
+    update(id, values) {
+        return this.repository.update(id, values);
+    }
+    /**
+     * Delete one row by primary key.
+     *
+     * @param id - Primary-key value.
+     * @returns Number of deleted rows.
+     */
+    delete(id) {
+        return this.repository.delete(id);
+    }
+    /**
+     * Insert or update according to unique columns.
+     *
+     * @param values - Column values.
+     * @param conflictColumns - Unique columns; defaults to the primary key.
+     * @returns Mutation metadata.
+     */
+    upsert(values, conflictColumns) {
+        return this.repository.upsert(values, conflictColumns);
+    }
+}

package/lib/database/service/stepService.d.ts

@@ -0,0 +1,23 @@
+import type { PrimaryKey } from "../entity/entity.js";
+import type { StepEntity } from "../entity/worker.js";
+import { StepRepository } from "../repository/workerRepository.js";
+import { Service } from "./service.js";
+export interface RecordStepInput {
+    pid: number;
+    tid: number;
+    at: string;
+    outcome: string;
+    usage: string;
+    note?: string;
+    receiptId?: string;
+}
+/**
+ * One service per entity: `steps`.
+ */
+export declare class StepService extends Service<StepEntity, PrimaryKey, StepRepository> {
+    constructor(steps: StepRepository);
+    byId(stepId: number): StepEntity | undefined;
+    byProcess(pid: number, limit?: number): StepEntity[];
+    byThread(tid: number, limit?: number): StepEntity[];
+    record(input: RecordStepInput): StepEntity;
+}

package/lib/database/service/stepService.js

@@ -0,0 +1,35 @@
+import { StepRepository } from "../repository/workerRepository.js";
+import { Service } from "./service.js";
+/**
+ * One service per entity: `steps`.
+ */
+export class StepService extends Service {
+    constructor(steps) {
+        super(steps, "Step");
+    }
+    byId(stepId) {
+        return this.findById(stepId);
+    }
+    byProcess(pid, limit = 200) {
+        return this.repository.byProcess(pid, limit);
+    }
+    byThread(tid, limit = 200) {
+        return this.repository.byThread(tid, limit);
+    }
+    record(input) {
+        const result = this.repository.insert({
+            pid: input.pid,
+            tid: input.tid,
+            at: input.at,
+            outcome: input.outcome,
+            usage: input.usage,
+            note: input.note ?? null,
+            receipt_id: input.receiptId ?? null,
+        });
+        const row = this.byId(Number(result.lastInsertRowid));
+        if (row === (void 0)) {
+            throw new Error("step was not stored");
+        }
+        return row;
+    }
+}

package/lib/database/service/threadService.d.ts

@@ -0,0 +1,23 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { PrimaryKey } from "../entity/entity.js";
+import type { ThreadEntity } from "../entity/thread.js";
+import { ThreadRepository } from "../repository/threadRepository.js";
+import type { ThreadClaim, ThreadPatch, ThreadRecord, ThreadSpec, ThreadState } from "../../thread/thread.js";
+import { Service } from "./service.js";
+/**
+ * One service per entity: `threads`.
+ */
+export declare class ThreadService extends Service<ThreadEntity, PrimaryKey, ThreadRepository> {
+    private readonly db;
+    constructor(db: DatabaseSync, threads: ThreadRepository);
+    byId(tid: number): ThreadEntity | undefined;
+    byProcess(pid: number): ThreadEntity[];
+    byGoal(goal: string): ThreadEntity[];
+    nextReady(): ThreadEntity | undefined;
+    spawn(spec: ThreadSpec, at: string): ThreadEntity;
+    record(tid: number): ThreadRecord;
+    list(pid?: number): ThreadRecord[];
+    claim(tid: number, workerId: string): ThreadClaim;
+    transition(tid: number, from: ThreadState | ThreadState[], to: ThreadState, patch?: ThreadPatch, lease?: number): ThreadRecord;
+    ready(): ThreadRecord | undefined;
+}

package/lib/database/service/threadService.js

@@ -0,0 +1,48 @@
+import { ThreadRepository } from "../repository/threadRepository.js";
+import { claimThread, getThread, listThreads, nextReadyThread, spawnThread, transitionThread } from "../../thread/thread.js";
+import { Service } from "./service.js";
+/**
+ * One service per entity: `threads`.
+ */
+export class ThreadService extends Service {
+    db;
+    constructor(db, threads) {
+        super(threads, "Thread");
+        this.db = db;
+    }
+    byId(tid) {
+        return this.findById(tid);
+    }
+    byProcess(pid) {
+        return this.repository.byProcess(pid);
+    }
+    byGoal(goal) {
+        return this.repository.byGoal(goal);
+    }
+    nextReady() {
+        return this.repository.nextReady();
+    }
+    spawn(spec, at) {
+        const record = spawnThread(this.db, spec, at);
+        const row = this.byId(record.tid);
+        if (row === (void 0)) {
+            throw new Error(`thread ${record.tid} was not stored`);
+        }
+        return row;
+    }
+    record(tid) {
+        return getThread(this.db, tid);
+    }
+    list(pid) {
+        return listThreads(this.db, pid);
+    }
+    claim(tid, workerId) {
+        return claimThread(this.db, tid, workerId);
+    }
+    transition(tid, from, to, patch = {}, lease) {
+        return transitionThread(this.db, tid, from, to, patch, lease);
+    }
+    ready() {
+        return nextReadyThread(this.db);
+    }
+}

package/lib/database/service/windowService.d.ts

@@ -0,0 +1,15 @@
+import type { PrimaryKey } from "../entity/entity.js";
+import type { WindowEntity, WindowPageEntity } from "../entity/window.js";
+import { WindowRepository } from "../repository/windowRepository.js";
+import type { WindowPageInput } from "../repository/windowRepository.js";
+import { Service } from "./service.js";
+/**
+ * One service per entity: `windows` (plus its `window_pages` children).
+ */
+export declare class WindowService extends Service<WindowEntity, PrimaryKey, WindowRepository> {
+    constructor(windows: WindowRepository);
+    get(tid: number): WindowEntity | undefined;
+    pages(tid: number): WindowPageEntity[];
+    save(tid: number, capacityTokens: number, usedTokens: number, at: string): void;
+    replacePages(tid: number, pages: readonly WindowPageInput[], at: string, capacityTokens: number): void;
+}

package/lib/database/service/windowService.js

@@ -0,0 +1,22 @@
+import { WindowRepository } from "../repository/windowRepository.js";
+import { Service } from "./service.js";
+/**
+ * One service per entity: `windows` (plus its `window_pages` children).
+ */
+export class WindowService extends Service {
+    constructor(windows) {
+        super(windows, "Window");
+    }
+    get(tid) {
+        return this.findById(tid);
+    }
+    pages(tid) {
+        return this.repository.pages(tid);
+    }
+    save(tid, capacityTokens, usedTokens, at) {
+        this.repository.save(tid, capacityTokens, usedTokens, at);
+    }
+    replacePages(tid, pages, at, capacityTokens) {
+        this.repository.replacePages(tid, pages, at, capacityTokens);
+    }
+}

package/lib/database/service/workerService.d.ts

@@ -0,0 +1,28 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { PrimaryKey } from "../entity/entity.js";
+import type { WorkerEntity } from "../entity/worker.js";
+import { WorkerRepository } from "../repository/workerRepository.js";
+import type { WorkerInput, WorkerRecord } from "../../concurrency/worker.js";
+import { Service } from "./service.js";
+/**
+ * Counts returned after recovering expired workers.
+ */
+export interface WorkerRecovery {
+    workers: string[];
+    threads: number;
+    processes: number;
+}
+/**
+ * One service per entity: `workers`.
+ */
+export declare class WorkerService extends Service<WorkerEntity, PrimaryKey, WorkerRepository> {
+    private readonly db;
+    constructor(db: DatabaseSync, workers: WorkerRepository);
+    byId(workerId: string): WorkerEntity | undefined;
+    list(): WorkerRecord[];
+    expired(at: string): WorkerEntity[];
+    register(input: WorkerInput, at: string): WorkerRecord;
+    heartbeat(workerId: string, at: string, leaseMs?: number): boolean;
+    unregister(workerId: string): void;
+    recover(at: string): WorkerRecovery;
+}

package/lib/database/service/workerService.js

@@ -0,0 +1,34 @@
+import { WorkerRepository } from "../repository/workerRepository.js";
+import { heartbeatWorker, listWorkers, recoverExpiredWorkers, registerWorker, unregisterWorker } from "../../concurrency/worker.js";
+import { Service } from "./service.js";
+/**
+ * One service per entity: `workers`.
+ */
+export class WorkerService extends Service {
+    db;
+    constructor(db, workers) {
+        super(workers, "Worker");
+        this.db = db;
+    }
+    byId(workerId) {
+        return this.findById(workerId);
+    }
+    list() {
+        return listWorkers(this.db);
+    }
+    expired(at) {
+        return this.repository.expired(at);
+    }
+    register(input, at) {
+        return registerWorker(this.db, input, at);
+    }
+    heartbeat(workerId, at, leaseMs) {
+        return heartbeatWorker(this.db, workerId, at, leaseMs);
+    }
+    unregister(workerId) {
+        unregisterWorker(this.db, workerId);
+    }
+    recover(at) {
+        return recoverExpiredWorkers(this.db, at);
+    }
+}

package/lib/database/sql/index.d.ts

@@ -0,0 +1,3 @@
+export { MetaSchema, Schema } from "./schema.js";
+export { assertSqlIdentifier, Sql, TableSql, toSqlParameter } from "./sql.js";
+export type { MutationResult, SelectOptions, SqlParameter } from "./sql.js";

package/lib/database/sql/index.js

@@ -0,0 +1,2 @@
+export { MetaSchema, Schema } from "./schema.js";
+export { assertSqlIdentifier, Sql, TableSql, toSqlParameter } from "./sql.js";

package/lib/database/sql/schema.d.ts

@@ -0,0 +1,5 @@
+/**
+ * DDL for the SQLite store. Migrations live in the store, not here.
+ */
+export declare const MetaSchema: string;
+export declare const Schema: string;