@lp-labs/task-checkpoint 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @lp-labs/task-checkpoint
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Canonical JSON checkpoint serialization, corruption checks, and validation primitives. This
+package is a serialization/checksum core only; it does not persist, schedule, or resume tasks.
+
+## Install
+
+```bash
+npm install @lp-labs/task-checkpoint
+```
+
+ES2022 ESM and CommonJS builds include TypeScript declarations.
+
+## Quickstart
+
+```js
+import {
+  createTaskCheckpoint,
+  parseTaskCheckpoint,
+  serializeTaskCheckpoint,
+} from '@lp-labs/task-checkpoint';
+
+const checkpoint = createTaskCheckpoint('job-17', 3, { completed: ['a'], remaining: 2 });
+const encoded = serializeTaskCheckpoint(checkpoint);
+const restored = parseTaskCheckpoint(encoded);
+if (restored.state.remaining !== 2) throw new Error('Checkpoint did not round-trip');
+```
+
+## API and customization
+
+- `createTaskCheckpoint(taskId, revision, state, options?)` copies and canonicalizes JSON state,
+  sorts object keys, and calculates its checksum.
+- `serializeTaskCheckpoint(checkpoint, options?)` validates its format and checksum before returning
+  JSON text.
+- `parseTaskCheckpoint<T>(text, options?)` parses, bounds, and validates serialized input.
+- `validateTaskCheckpoint<T>(input, options?)` validates an already-parsed value and returns a
+  detached checkpoint.
+- `CheckpointLimits` options are `maxBytes` (default 1 MiB), `maxDepth` (64), and `maxNodes`
+  (100,000). Limits can be customized per operation.
+
+Task IDs must be 1–256 characters; revisions are non-negative safe integers. State is plain JSON:
+null, booleans, strings, finite numbers, arrays, and plain objects. Cycles, undefined, functions,
+non-finite numbers, and class instances are rejected. Object keys are sorted so equivalent
+unordered records produce the same checksum.
+
+## Integrity and scope
+
+The checksum is a deterministic 64-bit FNV-1a corruption check, not a cryptographic signature,
+authentication mechanism, or protection against malicious modification. Treat serialized input as
+untrusted and apply application-level trust checks. JSON numbers retain JavaScript number semantics.
+No storage, compression, encryption, schema migration, task execution, or durability is provided.
+
+## Exports
+
+Runtime exports: `createTaskCheckpoint`, `serializeTaskCheckpoint`, `parseTaskCheckpoint`,
+`validateTaskCheckpoint`.
+TypeScript-only exports: `CheckpointValue`, `TaskCheckpoint`, `CheckpointLimits`.
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,26 @@
+declare const FORMAT = "lp-task-checkpoint";
+declare const FORMAT_VERSION = 1;
+export type CheckpointValue = null | boolean | number | string | CheckpointValue[] | {
+    [key: string]: CheckpointValue;
+};
+export interface TaskCheckpoint<T extends CheckpointValue = CheckpointValue> {
+    readonly format: typeof FORMAT;
+    readonly version: typeof FORMAT_VERSION;
+    readonly taskId: string;
+    readonly revision: number;
+    readonly checksum: string;
+    readonly state: T;
+}
+export interface CheckpointLimits {
+    readonly maxBytes?: number;
+    readonly maxDepth?: number;
+    readonly maxNodes?: number;
+}
+interface CheckpointOptions {
+    readonly limits?: CheckpointLimits;
+}
+export declare function createTaskCheckpoint<T extends CheckpointValue>(taskId: string, revision: number, state: T, options?: CheckpointOptions): TaskCheckpoint<T>;
+export declare function serializeTaskCheckpoint<T extends CheckpointValue>(checkpoint: TaskCheckpoint<T>, options?: CheckpointOptions): string;
+export declare function validateTaskCheckpoint<T extends CheckpointValue>(input: unknown, options?: CheckpointOptions): TaskCheckpoint<T>;
+export declare function parseTaskCheckpoint<T extends CheckpointValue = CheckpointValue>(serialized: string, options?: CheckpointOptions): TaskCheckpoint<T>;
+export {};

package/dist/cjs/index.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTaskCheckpoint = createTaskCheckpoint;
+exports.serializeTaskCheckpoint = serializeTaskCheckpoint;
+exports.validateTaskCheckpoint = validateTaskCheckpoint;
+exports.parseTaskCheckpoint = parseTaskCheckpoint;
+const FORMAT = 'lp-task-checkpoint';
+const FORMAT_VERSION = 1;
+const DEFAULT_MAX_BYTES = 1_048_576;
+const DEFAULT_MAX_DEPTH = 64;
+const DEFAULT_MAX_NODES = 100_000;
+function limitsOf(limits = {}) {
+    const result = {
+        maxBytes: limits.maxBytes ?? DEFAULT_MAX_BYTES,
+        maxDepth: limits.maxDepth ?? DEFAULT_MAX_DEPTH,
+        maxNodes: limits.maxNodes ?? DEFAULT_MAX_NODES,
+    };
+    if (!Number.isSafeInteger(result.maxBytes) ||
+        result.maxBytes < 1 ||
+        !Number.isSafeInteger(result.maxDepth) ||
+        result.maxDepth < 0 ||
+        !Number.isSafeInteger(result.maxNodes) ||
+        result.maxNodes < 1) {
+        throw new RangeError('Checkpoint limits must be positive safe integers (depth may be zero)');
+    }
+    return result;
+}
+function canonicalize(value, maxDepth, maxNodes) {
+    let nodes = 0;
+    const seen = new Set();
+    const visit = (item, depth) => {
+        nodes++;
+        if (nodes > maxNodes)
+            throw new RangeError('Checkpoint exceeds the configured node limit');
+        if (depth > maxDepth)
+            throw new RangeError('Checkpoint exceeds the configured depth limit');
+        if (item === null || typeof item === 'string' || typeof item === 'boolean')
+            return item;
+        if (typeof item === 'number' && Number.isFinite(item))
+            return item;
+        if (Array.isArray(item)) {
+            if (seen.has(item))
+                throw new TypeError('Checkpoint state cannot contain cycles');
+            seen.add(item);
+            const copy = Array.from(item, (entry) => visit(entry, depth + 1));
+            seen.delete(item);
+            return copy;
+        }
+        if (typeof item === 'object' && Object.getPrototypeOf(item) === Object.prototype) {
+            if (seen.has(item))
+                throw new TypeError('Checkpoint state cannot contain cycles');
+            seen.add(item);
+            const copy = {};
+            if (Object.getOwnPropertySymbols(item).length > 0) {
+                throw new TypeError('Checkpoint state cannot contain symbol keys');
+            }
+            for (const key of Object.keys(item).sort()) {
+                const entry = item[key];
+                if (entry === undefined)
+                    throw new TypeError('Checkpoint state cannot contain undefined');
+                Object.defineProperty(copy, key, {
+                    value: visit(entry, depth + 1),
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                });
+            }
+            seen.delete(item);
+            return copy;
+        }
+        throw new TypeError('Checkpoint state must contain only finite JSON values and plain objects');
+    };
+    return visit(value, 0);
+}
+function checksum(text) {
+    let hash = 0xcbf29ce484222325n;
+    for (const byte of new TextEncoder().encode(text)) {
+        hash ^= BigInt(byte);
+        hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+function checksumInput(taskId, revision, state) {
+    return JSON.stringify([FORMAT, FORMAT_VERSION, taskId, revision, state]);
+}
+function validateIdAndRevision(taskId, revision) {
+    if (typeof taskId !== 'string' || taskId.length === 0 || taskId.length > 256) {
+        throw new TypeError('taskId must be a non-empty string of at most 256 characters');
+    }
+    if (!Number.isSafeInteger(revision) || revision < 0) {
+        throw new RangeError('revision must be a non-negative safe integer');
+    }
+}
+function createTaskCheckpoint(taskId, revision, state, options = {}) {
+    validateIdAndRevision(taskId, revision);
+    const limits = limitsOf(options.limits);
+    const copy = canonicalize(state, limits.maxDepth, limits.maxNodes);
+    const result = {
+        format: FORMAT,
+        version: FORMAT_VERSION,
+        taskId,
+        revision,
+        checksum: checksum(checksumInput(taskId, revision, copy)),
+        state: copy,
+    };
+    if (new TextEncoder().encode(JSON.stringify(result)).byteLength > limits.maxBytes) {
+        throw new RangeError('Checkpoint exceeds the configured byte limit');
+    }
+    return result;
+}
+function serializeTaskCheckpoint(checkpoint, options = {}) {
+    const validated = validateTaskCheckpoint(checkpoint, options);
+    return JSON.stringify(validated);
+}
+function validateTaskCheckpoint(input, options = {}) {
+    if (typeof input !== 'object' ||
+        input === null ||
+        Array.isArray(input) ||
+        Object.getPrototypeOf(input) !== Object.prototype) {
+        throw new TypeError('Checkpoint must be a plain object');
+    }
+    const value = input;
+    const allowedKeys = new Set(['format', 'version', 'taskId', 'revision', 'checksum', 'state']);
+    if (Object.keys(value).some((key) => !allowedKeys.has(key))) {
+        throw new TypeError('Checkpoint contains unknown fields');
+    }
+    if (value.format !== FORMAT || value.version !== FORMAT_VERSION) {
+        throw new TypeError('Unsupported checkpoint format or version');
+    }
+    if (typeof value.checksum !== 'string')
+        throw new TypeError('Checkpoint checksum is missing');
+    const checkpoint = createTaskCheckpoint(value.taskId, value.revision, value.state, options);
+    if (value.checksum !== checkpoint.checksum)
+        throw new TypeError('Checkpoint checksum mismatch');
+    return checkpoint;
+}
+function parseTaskCheckpoint(serialized, options = {}) {
+    const maxBytes = limitsOf(options.limits).maxBytes;
+    if (typeof serialized !== 'string')
+        throw new TypeError('Serialized checkpoint must be a string');
+    if (new TextEncoder().encode(serialized).byteLength > maxBytes) {
+        throw new RangeError('Checkpoint exceeds the configured byte limit');
+    }
+    let input;
+    try {
+        input = JSON.parse(serialized);
+    }
+    catch {
+        throw new TypeError('Serialized checkpoint is not valid JSON');
+    }
+    return validateTaskCheckpoint(input, options);
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,26 @@
+declare const FORMAT = "lp-task-checkpoint";
+declare const FORMAT_VERSION = 1;
+export type CheckpointValue = null | boolean | number | string | CheckpointValue[] | {
+    [key: string]: CheckpointValue;
+};
+export interface TaskCheckpoint<T extends CheckpointValue = CheckpointValue> {
+    readonly format: typeof FORMAT;
+    readonly version: typeof FORMAT_VERSION;
+    readonly taskId: string;
+    readonly revision: number;
+    readonly checksum: string;
+    readonly state: T;
+}
+export interface CheckpointLimits {
+    readonly maxBytes?: number;
+    readonly maxDepth?: number;
+    readonly maxNodes?: number;
+}
+interface CheckpointOptions {
+    readonly limits?: CheckpointLimits;
+}
+export declare function createTaskCheckpoint<T extends CheckpointValue>(taskId: string, revision: number, state: T, options?: CheckpointOptions): TaskCheckpoint<T>;
+export declare function serializeTaskCheckpoint<T extends CheckpointValue>(checkpoint: TaskCheckpoint<T>, options?: CheckpointOptions): string;
+export declare function validateTaskCheckpoint<T extends CheckpointValue>(input: unknown, options?: CheckpointOptions): TaskCheckpoint<T>;
+export declare function parseTaskCheckpoint<T extends CheckpointValue = CheckpointValue>(serialized: string, options?: CheckpointOptions): TaskCheckpoint<T>;
+export {};

package/dist/esm/index.js

@@ -0,0 +1,146 @@
+const FORMAT = 'lp-task-checkpoint';
+const FORMAT_VERSION = 1;
+const DEFAULT_MAX_BYTES = 1_048_576;
+const DEFAULT_MAX_DEPTH = 64;
+const DEFAULT_MAX_NODES = 100_000;
+function limitsOf(limits = {}) {
+    const result = {
+        maxBytes: limits.maxBytes ?? DEFAULT_MAX_BYTES,
+        maxDepth: limits.maxDepth ?? DEFAULT_MAX_DEPTH,
+        maxNodes: limits.maxNodes ?? DEFAULT_MAX_NODES,
+    };
+    if (!Number.isSafeInteger(result.maxBytes) ||
+        result.maxBytes < 1 ||
+        !Number.isSafeInteger(result.maxDepth) ||
+        result.maxDepth < 0 ||
+        !Number.isSafeInteger(result.maxNodes) ||
+        result.maxNodes < 1) {
+        throw new RangeError('Checkpoint limits must be positive safe integers (depth may be zero)');
+    }
+    return result;
+}
+function canonicalize(value, maxDepth, maxNodes) {
+    let nodes = 0;
+    const seen = new Set();
+    const visit = (item, depth) => {
+        nodes++;
+        if (nodes > maxNodes)
+            throw new RangeError('Checkpoint exceeds the configured node limit');
+        if (depth > maxDepth)
+            throw new RangeError('Checkpoint exceeds the configured depth limit');
+        if (item === null || typeof item === 'string' || typeof item === 'boolean')
+            return item;
+        if (typeof item === 'number' && Number.isFinite(item))
+            return item;
+        if (Array.isArray(item)) {
+            if (seen.has(item))
+                throw new TypeError('Checkpoint state cannot contain cycles');
+            seen.add(item);
+            const copy = Array.from(item, (entry) => visit(entry, depth + 1));
+            seen.delete(item);
+            return copy;
+        }
+        if (typeof item === 'object' && Object.getPrototypeOf(item) === Object.prototype) {
+            if (seen.has(item))
+                throw new TypeError('Checkpoint state cannot contain cycles');
+            seen.add(item);
+            const copy = {};
+            if (Object.getOwnPropertySymbols(item).length > 0) {
+                throw new TypeError('Checkpoint state cannot contain symbol keys');
+            }
+            for (const key of Object.keys(item).sort()) {
+                const entry = item[key];
+                if (entry === undefined)
+                    throw new TypeError('Checkpoint state cannot contain undefined');
+                Object.defineProperty(copy, key, {
+                    value: visit(entry, depth + 1),
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                });
+            }
+            seen.delete(item);
+            return copy;
+        }
+        throw new TypeError('Checkpoint state must contain only finite JSON values and plain objects');
+    };
+    return visit(value, 0);
+}
+function checksum(text) {
+    let hash = 0xcbf29ce484222325n;
+    for (const byte of new TextEncoder().encode(text)) {
+        hash ^= BigInt(byte);
+        hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+function checksumInput(taskId, revision, state) {
+    return JSON.stringify([FORMAT, FORMAT_VERSION, taskId, revision, state]);
+}
+function validateIdAndRevision(taskId, revision) {
+    if (typeof taskId !== 'string' || taskId.length === 0 || taskId.length > 256) {
+        throw new TypeError('taskId must be a non-empty string of at most 256 characters');
+    }
+    if (!Number.isSafeInteger(revision) || revision < 0) {
+        throw new RangeError('revision must be a non-negative safe integer');
+    }
+}
+export function createTaskCheckpoint(taskId, revision, state, options = {}) {
+    validateIdAndRevision(taskId, revision);
+    const limits = limitsOf(options.limits);
+    const copy = canonicalize(state, limits.maxDepth, limits.maxNodes);
+    const result = {
+        format: FORMAT,
+        version: FORMAT_VERSION,
+        taskId,
+        revision,
+        checksum: checksum(checksumInput(taskId, revision, copy)),
+        state: copy,
+    };
+    if (new TextEncoder().encode(JSON.stringify(result)).byteLength > limits.maxBytes) {
+        throw new RangeError('Checkpoint exceeds the configured byte limit');
+    }
+    return result;
+}
+export function serializeTaskCheckpoint(checkpoint, options = {}) {
+    const validated = validateTaskCheckpoint(checkpoint, options);
+    return JSON.stringify(validated);
+}
+export function validateTaskCheckpoint(input, options = {}) {
+    if (typeof input !== 'object' ||
+        input === null ||
+        Array.isArray(input) ||
+        Object.getPrototypeOf(input) !== Object.prototype) {
+        throw new TypeError('Checkpoint must be a plain object');
+    }
+    const value = input;
+    const allowedKeys = new Set(['format', 'version', 'taskId', 'revision', 'checksum', 'state']);
+    if (Object.keys(value).some((key) => !allowedKeys.has(key))) {
+        throw new TypeError('Checkpoint contains unknown fields');
+    }
+    if (value.format !== FORMAT || value.version !== FORMAT_VERSION) {
+        throw new TypeError('Unsupported checkpoint format or version');
+    }
+    if (typeof value.checksum !== 'string')
+        throw new TypeError('Checkpoint checksum is missing');
+    const checkpoint = createTaskCheckpoint(value.taskId, value.revision, value.state, options);
+    if (value.checksum !== checkpoint.checksum)
+        throw new TypeError('Checkpoint checksum mismatch');
+    return checkpoint;
+}
+export function parseTaskCheckpoint(serialized, options = {}) {
+    const maxBytes = limitsOf(options.limits).maxBytes;
+    if (typeof serialized !== 'string')
+        throw new TypeError('Serialized checkpoint must be a string');
+    if (new TextEncoder().encode(serialized).byteLength > maxBytes) {
+        throw new RangeError('Checkpoint exceeds the configured byte limit');
+    }
+    let input;
+    try {
+        input = JSON.parse(serialized);
+    }
+    catch {
+        throw new TypeError('Serialized checkpoint is not valid JSON');
+    }
+    return validateTaskCheckpoint(input, options);
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/task-checkpoint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Canonical bounded JSON task checkpoint serialization, checksum, and validation without persistence.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build && node scripts/check-types.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}