jg-agent-hq 2.0.0 → 3.0.0

package/dist/snapshots/types.d.ts

@@ -158,8 +158,19 @@ export declare const SnapshotWorkerResponseSchema: z.ZodDiscriminatedUnion<[z.Zo
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"error">;
     code: z.ZodEnum<{
+        JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: "JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED";
         JG_AGENT_HQ_SNAPSHOT_INVALID: "JG_AGENT_HQ_SNAPSHOT_INVALID";
         JG_AGENT_HQ_SNAPSHOT_FAILED: "JG_AGENT_HQ_SNAPSHOT_FAILED";
     }>;
     message: z.ZodString;
 }, z.core.$strip>], "kind">;
+export type ISnapshotSource = {
+    stateRoot: string;
+    coordinationRoot: string;
+    allowedRoots: string[];
+    actionKeyHash: string;
+    schemaHash: string;
+    backupDatabase: (path: string) => Promise<unknown>;
+    readPlans: (after: string) => Promise<string[]>;
+    verify: (directory: string) => Promise<IHqSnapshotInspection>;
+};

package/dist/snapshots/types.js

@@ -60,7 +60,11 @@ export const SnapshotWorkerResponseSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('result'), result: SnapshotInspectionSchema }),
     z.object({
         kind: z.literal('error'),
-        code: z.enum(['JG_AGENT_HQ_SNAPSHOT_INVALID', 'JG_AGENT_HQ_SNAPSHOT_FAILED']),
+        code: z.enum([
+            'JG_AGENT_HQ_SNAPSHOT_INVALID',
+            'JG_AGENT_HQ_SNAPSHOT_FAILED',
+            'JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED',
+        ]),
         message: z.string(),
     }),
 ]);

package/dist/storage/index.d.ts

@@ -1,4 +1,5 @@
-export { StorageDescriptorSchema, StorageStampSchema } from './types.js';
+export { StorageDescriptorSchema } from './types.js';
+export { StorageStampSchema } from './schema/index.js';
 export type { IStorageDescriptor, IStorageMaintenanceOperation } from './types.js';
 export { STORAGE_CONNECTION_SETTINGS } from './constants.js';
 export { createStorage } from './storage.js';

package/dist/storage/index.js

@@ -1,5 +1,6 @@
 // types and validated worker metadata
-export { StorageDescriptorSchema, StorageStampSchema } from './types.js';
+export { StorageDescriptorSchema } from './types.js';
+export { StorageStampSchema } from './schema/index.js';
 // required connection settings
 export { STORAGE_CONNECTION_SETTINGS } from './constants.js';
 // runtime maintenance admission

package/dist/storage/schema/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const V1_SCHEMA_HASH = "af0686f5f4a2af3cbe033a9aab2982d041a4cb0b2fc47088bdd9e15963c66fee";
+export declare const CURRENT_SCHEMA_VERSION = 2;

package/dist/storage/schema/constants.js

@@ -0,0 +1,3 @@
+// exact published 2.0.0 schema; this compatibility asset must never follow the current schema
+export const V1_SCHEMA_HASH = 'af0686f5f4a2af3cbe033a9aab2982d041a4cb0b2fc47088bdd9e15963c66fee';
+export const CURRENT_SCHEMA_VERSION = 2;

package/dist/storage/schema/index.d.ts

@@ -0,0 +1,4 @@
+export { StorageStampSchema } from './types.js';
+export type { IStorageSchema, IStorageMigration } from './types.js';
+export { CURRENT_SCHEMA_VERSION, V1_SCHEMA_HASH } from './constants.js';
+export { STORAGE_SCHEMAS, STORAGE_MIGRATIONS, readStorageSchema } from './schema.js';

package/dist/storage/schema/index.js

@@ -0,0 +1,5 @@
+// contracts
+export { StorageStampSchema } from './types.js';
+// lineage and recognition
+export { CURRENT_SCHEMA_VERSION, V1_SCHEMA_HASH } from './constants.js';
+export { STORAGE_SCHEMAS, STORAGE_MIGRATIONS, readStorageSchema } from './schema.js';

package/dist/storage/schema/schema.d.ts

@@ -0,0 +1,16 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type IStorageSchema, type IStorageMigration } from './types.js';
+export declare const STORAGE_SCHEMAS: IStorageSchema[];
+export declare const STORAGE_MIGRATIONS: IStorageMigration[];
+/**
+ * Recognizes one supported stamp without writing or adopting an arbitrary database.
+ * @returns The registered lineage and key hash, or null for a completely empty database.
+ * @throws
+ * - JG_AGENT_HQ_STORAGE_INVALID: The HQ storage is invalid
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
+ * - JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE: The HQ action key is unavailable
+ */
+export declare const readStorageSchema: (database: DatabaseSync, actionKeyHash?: string) => {
+    schema: IStorageSchema;
+    actionKeyHash: string;
+} | null;

package/dist/storage/schema/schema.js

@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs';
+import { hashValue } from 'jg-crypto';
+import { Exception, isException, extractMessage } from 'jg-exception';
+import { CURRENT_SCHEMA_VERSION, V1_SCHEMA_HASH } from './constants.js';
+import { StorageStampSchema } from './types.js';
+// package-owned SQL is small and immutable during a process lifetime
+export const STORAGE_SCHEMAS = [
+    { version: 1, hash: V1_SCHEMA_HASH, restoreFenceVersion: 1 },
+    {
+        version: CURRENT_SCHEMA_VERSION,
+        hash: hashValue(readFileSync(new URL('../../store/schema.sql', import.meta.url))),
+        restoreFenceVersion: 1,
+    },
+];
+export const STORAGE_MIGRATIONS = [
+    { fromVersion: 1, toVersion: 2, source: new URL('./v1-to-v2.sql', import.meta.url) },
+];
+/**
+ * Recognizes one supported stamp without writing or adopting an arbitrary database.
+ * @returns The registered lineage and key hash, or null for a completely empty database.
+ * @throws
+ * - JG_AGENT_HQ_STORAGE_INVALID: The HQ storage is invalid
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
+ * - JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE: The HQ action key is unavailable
+ */
+export const readStorageSchema = (database, actionKeyHash) => {
+    try {
+        if (!database.prepare('SELECT 1 FROM sqlite_schema LIMIT 1').get())
+            return null;
+        const hasVersion = database
+            .prepare('PRAGMA table_xinfo(hq_schema)')
+            .all()
+            .some((column) => column.name === 'schema_version');
+        const rows = database
+            .prepare(`SELECT id, schema_hash, action_key_hash${hasVersion ? ', schema_version' : ''} FROM hq_schema LIMIT 2`)
+            .all();
+        const parsed = StorageStampSchema.safeParse(rows.length === 1 ? rows[0] : null);
+        if (!parsed.success)
+            throw new Exception('The HQ storage is invalid', {
+                code: 'JG_AGENT_HQ_STORAGE_INVALID',
+                data: { kind: 'state-conflict' },
+            });
+        const stamp = parsed.data;
+        const schema = hasVersion
+            ? STORAGE_SCHEMAS.find((entry) => entry.version === stamp.schema_version)
+            : STORAGE_SCHEMAS.find((entry) => entry.version === 1 && entry.hash === stamp.schema_hash);
+        if (!schema)
+            throw new Exception('The HQ storage version is unsupported', {
+                code: 'JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED',
+                data: { kind: 'state-conflict' },
+            });
+        if (schema.hash !== stamp.schema_hash)
+            throw new Exception('The HQ storage is invalid', {
+                code: 'JG_AGENT_HQ_STORAGE_INVALID',
+                data: { kind: 'state-conflict' },
+            });
+        if (actionKeyHash !== undefined && stamp.action_key_hash !== actionKeyHash)
+            throw new Exception('The HQ action key is unavailable', {
+                code: 'JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE',
+                data: { kind: 'state-conflict' },
+            });
+        return { schema, actionKeyHash: stamp.action_key_hash };
+    }
+    catch (cause) {
+        if (isException(cause))
+            throw cause;
+        throw new Exception(`The HQ storage is invalid: ${extractMessage(cause)}`, {
+            code: 'JG_AGENT_HQ_STORAGE_INVALID',
+            data: { kind: 'state-conflict' },
+            cause,
+        });
+    }
+};

package/dist/storage/schema/types.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const StorageStampSchema: z.ZodObject<{
+    id: z.ZodLiteral<1>;
+    schema_hash: z.ZodString;
+    action_key_hash: z.ZodString;
+    schema_version: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type IStorageSchema = {
+    version: number;
+    hash: string;
+    restoreFenceVersion: number | null;
+};
+export type IStorageMigration = {
+    fromVersion: number;
+    toVersion: number;
+    source: URL;
+};

package/dist/storage/schema/types.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+// singleton identity; an absent version is accepted only for the exact published baseline
+export const StorageStampSchema = z.object({
+    id: z.literal(1),
+    schema_hash: z.string().regex(/^[a-f0-9]{64}$/),
+    action_key_hash: z.string().regex(/^[a-f0-9]{64}$/),
+    schema_version: z.number().int().positive().safe().optional(),
+});

package/dist/storage/schema/v1-to-v2.sql

@@ -0,0 +1 @@
+ALTER TABLE hq_schema ADD COLUMN schema_version INTEGER NOT NULL DEFAULT 2 CHECK (schema_version > 0);