@totemsdk/industrial-action 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Totem SDK Contributors
+
+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

@@ -0,0 +1,114 @@
+# @totemsdk/industrial-action
+
+Deterministic industrial action lifecycle for Totem Edge — converts governed intent into context-aware, bounded, verifiably executed operations on field devices and protocols.
+
+## Install
+
+```bash
+npm install @totemsdk/industrial-action
+```
+
+## Design
+
+This package sits between governance/authority (intent + mandate) and edge protocol transports (OPC-UA, Modbus, BACnet, etc.). It provides:
+
+- **Action definition & schema** — declare parameter and context schemas per action kind
+- **Proposal lifecycle** — propose, validate commitment, check expiry, verify executability
+- **Commitment hashing** — domain-prefixed SHA3-256 canonical binding prevents parameter tampering
+- **Guardrails / conditions** — evaluate pre-execution constraints (parameter range, context match, time window, custom)
+- **Executor abstraction** — plugin executors per action kind, confirmed/failed/unknown status mapping
+- **Governance bridge** — reserve-before-execute, commit-on-confirmed, abort-on-failure flow
+- **Action receipts** — verifiable proof records with integrity checks
+- **Registry** — register definitions and executors, lookup by kind
+
+## Quick start
+
+```ts
+import { createProposal, createActionDefinition, executeAction, ActionRegistry, evaluateConditions } from '@totemsdk/industrial-action';
+import type { ActionSchema, Condition } from '@totemsdk/industrial-action';
+
+// 1. Define schema
+const setTempSchema: ActionSchema = {
+  parameters: [
+    { name: 'setpoint', type: 'number', required: true },
+    { name: 'rampRate', type: 'number', required: false },
+  ],
+  context: [
+    { name: 'zoneId', type: 'string', required: true },
+  ],
+};
+
+// 2. Create definition
+const setTempDef = createActionDefinition('temp.set', 'Set temperature setpoint', setTempSchema, {
+  async execute(params, context) {
+    // send to PLC / BACnet / OPC-UA
+    return { ok: true, data: { applied: true } };
+  },
+});
+
+// 3. Register
+const registry = new ActionRegistry();
+registry.registerDefinition(setTempDef);
+
+// 4. Create proposal
+const proposal = createProposal({
+  kind: 'temp.set',
+  parameters: { setpoint: 22.5, rampRate: 1.0 },
+  context: { zoneId: 'HVAC-03' },
+});
+
+// 5. Check conditions
+const guards: Condition[] = [
+  { type: 'parameter_range', field: 'setpoint', operator: 'gte', value: 10 },
+  { type: 'parameter_range', field: 'setpoint', operator: 'lte', value: 35 },
+];
+const { passed, failed } = evaluateConditions(guards, proposal.parameters, proposal.context);
+
+// 6. Execute
+if (passed) {
+  const { execution, receipt } = await executeAction(proposal, { kind: 'temp.set', execute: setTempDef.handler.execute }, proposal.context);
+  console.log(execution.status); // 'confirmed' | 'failed' | 'unknown'
+}
+```
+
+## API
+
+### Core types
+- `ActionProposal` — proposed action with commitment hash, expiry, optional authority decision
+- `ActionExecution` — execution record with status, result, error, receipt
+- `ActionReceipt` — verifiable proof of action outcome
+- `IndustrialActionDefinition` — action kind + schema + handler
+- `ActionSchema` — parameter and context field schemas
+- `Condition` — guardrail with field, operator, value, custom evaluator
+
+### Key functions
+| Function | Purpose |
+|----------|---------|
+| `createProposal` | Create action proposal with computed ID and commitment hash |
+| `verifyCommitment` | Check proposal integrity against tampering |
+| `createActionDefinition` | Define an action kind with schema |
+| `validateParameters` / `validateContext` | Validate inputs against schema |
+| `evaluateConditions` | Evaluate guardrails before execution |
+| `executeAction` | Run executor, map result to confirmed/failed/unknown |
+| `createReceipt` / `verifyReceiptIntegrity` | Create and verify action receipts |
+| `createGovernanceBridge` | Wrap reserve/commit/abort for governance integration |
+
+### Errors
+- `IndustrialActionError` (base)
+- `ActionValidationError` — parameter/context validation failures
+- `ActionCommitmentError` — commitment hash mismatch
+- `ActionConditionError` — guardrail violations
+- `ActionExecutionError` — executor failures
+- `ActionGovernanceError` — governance bridge failures
+- `ActionDefinitionError` — registry/definition issues
+
+## Dependencies
+
+- `@totemsdk/core` — SHA3-256 hashing
+- `@totemsdk/proof` — proof types
+- `@totemsdk/authority` — mandate types
+- `@totemsdk/edge` — `EdgeOperationResult`
+
+## License
+
+MIT

package/dist/canonical.d.ts

@@ -0,0 +1,3 @@
+export declare function toHex(bytes: Uint8Array): string;
+export declare function canonicalJson(value: unknown): string;
+export declare function hashCanonical(domain: string, value: unknown): string;

package/dist/canonical.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toHex = toHex;
+exports.canonicalJson = canonicalJson;
+exports.hashCanonical = hashCanonical;
+const core_1 = require("@totemsdk/core");
+function toHex(bytes) {
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(canonicalJson).join(',') + ']';
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const pairs = keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`);
+    return '{' + pairs.join(',') + '}';
+}
+function hashCanonical(domain, value) {
+    const input = domain + canonicalJson(value);
+    return toHex((0, core_1.sha3_256)(new TextEncoder().encode(input)));
+}

package/dist/commitment.d.ts

@@ -0,0 +1,8 @@
+import type { ActionProposal } from './types.js';
+export declare function createCommitment(proposal: {
+    kind: string;
+    parameters: Record<string, unknown>;
+    context: Record<string, unknown>;
+}): string;
+export declare function verifyCommitmentBinding(proposal: ActionProposal): boolean;
+export declare function serializeCommitmentPayload(proposal: ActionProposal): string;

package/dist/commitment.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCommitment = createCommitment;
+exports.verifyCommitmentBinding = verifyCommitmentBinding;
+exports.serializeCommitmentPayload = serializeCommitmentPayload;
+const ids_js_1 = require("./ids.js");
+const canonical_js_1 = require("./canonical.js");
+function createCommitment(proposal) {
+    return (0, ids_js_1.computeCommitmentHash)(proposal);
+}
+function verifyCommitmentBinding(proposal) {
+    const expected = createCommitment(proposal);
+    return proposal.commitmentHash === expected;
+}
+function serializeCommitmentPayload(proposal) {
+    return (0, canonical_js_1.canonicalJson)({
+        id: proposal.id,
+        kind: proposal.kind,
+        commitmentHash: proposal.commitmentHash,
+        parameters: proposal.parameters,
+        context: proposal.context,
+    });
+}

package/dist/condition.d.ts

@@ -0,0 +1,5 @@
+import type { Condition, ConditionResult } from './types.js';
+export declare function evaluateConditions(conditions: Condition[], params: Record<string, unknown>, context: Record<string, unknown>): ConditionResult;
+export declare function createCondition(params: Pick<Condition, 'type' | 'field' | 'operator' | 'value'> & {
+    evaluate?: Condition['evaluate'];
+}): Condition;

package/dist/condition.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateConditions = evaluateConditions;
+exports.createCondition = createCondition;
+function evaluateConditions(conditions, params, context) {
+    const failed = [];
+    for (const condition of conditions) {
+        const reason = evaluateCondition(condition, params, context);
+        if (reason !== null) {
+            failed.push({ condition, reason });
+        }
+    }
+    return { passed: failed.length === 0, failed };
+}
+function evaluateCondition(condition, params, context) {
+    if (condition.evaluate) {
+        return condition.evaluate(params, context);
+    }
+    const value = resolveField(condition.field, params, context);
+    if (value === undefined && condition.operator !== 'neq') {
+        return `field '${condition.field}' not found`;
+    }
+    return applyOperator(condition.operator ?? 'eq', value, condition.value, condition.field ?? '');
+}
+function resolveField(field, params, context) {
+    if (field === undefined)
+        return undefined;
+    if (field.startsWith('context.')) {
+        return context[field.slice(8)];
+    }
+    if (field.startsWith('params.')) {
+        return params[field.slice(7)];
+    }
+    return params[field] ?? context[field];
+}
+function applyOperator(operator, actual, expected, field) {
+    switch (operator) {
+        case 'eq':
+            return actual === expected ? null : `'${field}': expected ${String(expected)}, got ${String(actual)}`;
+        case 'neq':
+            return actual !== expected ? null : `'${field}': expected not equal to ${String(expected)}`;
+        case 'gt':
+            return typeof actual === 'number' && typeof expected === 'number' && actual > expected
+                ? null
+                : `'${field}': expected > ${String(expected)}, got ${String(actual)}`;
+        case 'gte':
+            return typeof actual === 'number' && typeof expected === 'number' && actual >= expected
+                ? null
+                : `'${field}': expected >= ${String(expected)}, got ${String(actual)}`;
+        case 'lt':
+            return typeof actual === 'number' && typeof expected === 'number' && actual < expected
+                ? null
+                : `'${field}': expected < ${String(expected)}, got ${String(actual)}`;
+        case 'lte':
+            return typeof actual === 'number' && typeof expected === 'number' && actual <= expected
+                ? null
+                : `'${field}': expected <= ${String(expected)}, got ${String(actual)}`;
+        case 'in':
+            return Array.isArray(expected) && expected.includes(actual)
+                ? null
+                : `'${field}': ${String(actual)} not in [${String(expected)}]`;
+        case 'not_in':
+            return Array.isArray(expected) && !expected.includes(actual)
+                ? null
+                : `'${field}': ${String(actual)} is in [${String(expected)}]`;
+        default:
+            return `unknown operator '${operator}'`;
+    }
+}
+function createCondition(params) {
+    return { ...params };
+}

package/dist/definition.d.ts

@@ -0,0 +1,14 @@
+import type { IndustrialActionDefinition, ActionSchema, ParameterType } from './types.js';
+export declare function createActionDefinition<TParameters = unknown, TResult = unknown>(kind: string, description: string, schema: ActionSchema, handler: {
+    execute(params: TParameters, context: Record<string, unknown>): Promise<{
+        ok: boolean;
+        data?: TResult;
+        error?: string;
+        errorCode?: string;
+    }>;
+}): IndustrialActionDefinition<TParameters, TResult>;
+export declare function validateParameters(schema: ActionSchema, parameters: Record<string, unknown>): string[];
+export declare function validateContext(schema: ActionSchema, context: Record<string, unknown>, now: number): string[];
+export declare function checkType(expected: ParameterType, value: unknown): string | null;
+export declare function assertValidParameters(schema: ActionSchema, parameters: Record<string, unknown>): void;
+export declare function assertValidContext(schema: ActionSchema, context: Record<string, unknown>, now: number): void;

package/dist/definition.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createActionDefinition = createActionDefinition;
+exports.validateParameters = validateParameters;
+exports.validateContext = validateContext;
+exports.checkType = checkType;
+exports.assertValidParameters = assertValidParameters;
+exports.assertValidContext = assertValidContext;
+const errors_js_1 = require("./errors.js");
+function createActionDefinition(kind, description, schema, handler) {
+    return { kind, description, schema, handler };
+}
+function validateParameters(schema, parameters) {
+    const errors = [];
+    for (const field of schema.parameters) {
+        const value = parameters[field.name];
+        if (value === undefined || value === null) {
+            if (field.required) {
+                errors.push(`parameter '${field.name}' is required`);
+            }
+            continue;
+        }
+        const typeErr = checkType(field.type, value);
+        if (typeErr) {
+            errors.push(`parameter '${field.name}': ${typeErr}`);
+        }
+        if (field.validation) {
+            const validationErr = field.validation(value);
+            if (validationErr) {
+                errors.push(`parameter '${field.name}': ${validationErr}`);
+            }
+        }
+    }
+    return errors;
+}
+function validateContext(schema, context, now) {
+    const errors = [];
+    for (const field of schema.context) {
+        const value = context[field.name];
+        if (value === undefined || value === null) {
+            if (field.required) {
+                errors.push(`context '${field.name}' is required`);
+            }
+            continue;
+        }
+        const typeErr = checkType(field.type, value);
+        if (typeErr) {
+            errors.push(`context '${field.name}': ${typeErr}`);
+        }
+    }
+    return errors;
+}
+function checkType(expected, value) {
+    switch (expected) {
+        case 'string':
+            return typeof value === 'string' ? null : `expected string, got ${typeof value}`;
+        case 'number':
+            return typeof value === 'number' ? null : `expected number, got ${typeof value}`;
+        case 'boolean':
+            return typeof value === 'boolean' ? null : `expected boolean, got ${typeof value}`;
+        case 'object':
+            return typeof value === 'object' && value !== null && !Array.isArray(value)
+                ? null
+                : `expected object, got ${typeof value}`;
+        case 'array':
+            return Array.isArray(value) ? null : `expected array, got ${typeof value}`;
+        default:
+            return `unknown type '${expected}'`;
+    }
+}
+function assertValidParameters(schema, parameters) {
+    const errors = validateParameters(schema, parameters);
+    if (errors.length > 0) {
+        throw new errors_js_1.ActionValidationError('parameter validation failed', { errors });
+    }
+}
+function assertValidContext(schema, context, now) {
+    const errors = validateContext(schema, context, now);
+    if (errors.length > 0) {
+        throw new errors_js_1.ActionValidationError('context validation failed', { errors });
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,23 @@
+export declare class IndustrialActionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class ActionDefinitionError extends IndustrialActionError {
+    constructor(message: string);
+}
+export declare class ActionValidationError extends IndustrialActionError {
+    readonly details: Record<string, unknown>;
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class ActionExecutionError extends IndustrialActionError {
+    constructor(message: string);
+}
+export declare class ActionConditionError extends IndustrialActionError {
+    constructor(message: string);
+}
+export declare class ActionGovernanceError extends IndustrialActionError {
+    constructor(message: string);
+}
+export declare class ActionCommitmentError extends IndustrialActionError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionCommitmentError = exports.ActionGovernanceError = exports.ActionConditionError = exports.ActionExecutionError = exports.ActionValidationError = exports.ActionDefinitionError = exports.IndustrialActionError = void 0;
+class IndustrialActionError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'IndustrialActionError';
+        this.code = code;
+    }
+}
+exports.IndustrialActionError = IndustrialActionError;
+class ActionDefinitionError extends IndustrialActionError {
+    constructor(message) {
+        super('ACTION_DEFINITION_ERROR', message);
+        this.name = 'ActionDefinitionError';
+    }
+}
+exports.ActionDefinitionError = ActionDefinitionError;
+class ActionValidationError extends IndustrialActionError {
+    constructor(message, details) {
+        super('ACTION_VALIDATION_ERROR', message);
+        this.name = 'ActionValidationError';
+        this.details = details ?? {};
+    }
+}
+exports.ActionValidationError = ActionValidationError;
+class ActionExecutionError extends IndustrialActionError {
+    constructor(message) {
+        super('ACTION_EXECUTION_ERROR', message);
+        this.name = 'ActionExecutionError';
+    }
+}
+exports.ActionExecutionError = ActionExecutionError;
+class ActionConditionError extends IndustrialActionError {
+    constructor(message) {
+        super('ACTION_CONDITION_ERROR', message);
+        this.name = 'ActionConditionError';
+    }
+}
+exports.ActionConditionError = ActionConditionError;
+class ActionGovernanceError extends IndustrialActionError {
+    constructor(message) {
+        super('ACTION_GOVERNANCE_ERROR', message);
+        this.name = 'ActionGovernanceError';
+    }
+}
+exports.ActionGovernanceError = ActionGovernanceError;
+class ActionCommitmentError extends IndustrialActionError {
+    constructor(message) {
+        super('ACTION_COMMITMENT_ERROR', message);
+        this.name = 'ActionCommitmentError';
+    }
+}
+exports.ActionCommitmentError = ActionCommitmentError;

package/dist/executor.d.ts

@@ -0,0 +1,2 @@
+import type { ActionProposal, ActionExecutor, ExecuteActionResult } from './types.js';
+export declare function executeAction(proposal: ActionProposal, executor: ActionExecutor, context: Record<string, unknown>, now?: number): Promise<ExecuteActionResult>;

package/dist/executor.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeAction = executeAction;
+const errors_js_1 = require("./errors.js");
+const ids_js_1 = require("./ids.js");
+const proposal_js_1 = require("./proposal.js");
+const definition_js_1 = require("./definition.js");
+async function executeAction(proposal, executor, context, now) {
+    const effectiveNow = now ?? Date.now();
+    (0, proposal_js_1.assertValidProposal)(proposal);
+    if (!(0, proposal_js_1.isProposalExecutable)(proposal, effectiveNow)) {
+        throw new errors_js_1.ActionValidationError('proposal is not executable');
+    }
+    (0, definition_js_1.assertValidParameters)(executor.kind === proposal.kind ? { parameters: [], context: [] } : { parameters: [], context: [] }, proposal.parameters);
+    (0, definition_js_1.assertValidContext)(executor.kind === proposal.kind ? { parameters: [], context: [] } : { parameters: [], context: [] }, context, effectiveNow);
+    const executionId = (0, ids_js_1.computeActionExecutionId)(proposal.id);
+    const execution = {
+        id: executionId,
+        proposalId: proposal.id,
+        status: 'executing',
+        startedAt: effectiveNow,
+    };
+    try {
+        const result = await executor.execute(proposal, proposal.parameters, context);
+        execution.status = result.ok ? 'confirmed' : 'failed';
+        execution.completedAt = Date.now();
+        if (result.ok) {
+            execution.result = result.data;
+        }
+        else {
+            execution.error = { code: result.errorCode ?? 'EXECUTION_FAILED', message: result.error ?? 'execution returned failure' };
+        }
+    }
+    catch (err) {
+        execution.status = 'unknown';
+        execution.completedAt = Date.now();
+        execution.error = {
+            code: 'EXECUTION_ERROR',
+            message: err instanceof Error ? err.message : 'unknown execution error',
+        };
+    }
+    const receipt = {
+        receiptId: (0, ids_js_1.computeReceiptId)(execution.id, proposal.id),
+        actionId: execution.id,
+        proposalId: proposal.id,
+        kind: proposal.kind,
+        status: execution.status === 'confirmed' ? 'confirmed' : execution.status === 'failed' ? 'failed' : 'unknown',
+        commitmentHash: proposal.commitmentHash,
+        parameters: proposal.parameters,
+        result: execution.result,
+        error: execution.error,
+        issuedAt: execution.completedAt ?? Date.now(),
+    };
+    execution.receipt = receipt;
+    return { execution, receipt };
+}

package/dist/governance-bridge.d.ts

@@ -0,0 +1,3 @@
+import type { GovernanceBridge, ActionProposal } from './types.js';
+export declare function createGovernanceBridge(reserveFn: GovernanceBridge['reserve']): GovernanceBridge;
+export declare function checkGovernanceConstraints(proposal: ActionProposal, now: number): string[];

package/dist/governance-bridge.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGovernanceBridge = createGovernanceBridge;
+exports.checkGovernanceConstraints = checkGovernanceConstraints;
+function createGovernanceBridge(reserveFn) {
+    return {
+        async reserve(proposal, mandateProofId) {
+            return reserveFn(proposal, mandateProofId);
+        },
+        async commit(reservationId, execution) {
+            return { ok: true };
+        },
+        async abort(reservationId, error) {
+            return { ok: true };
+        },
+    };
+}
+function checkGovernanceConstraints(proposal, now) {
+    const errors = [];
+    if (proposal.authorityDecision && !proposal.authorityDecision.allowed) {
+        errors.push(`authority decision denied: ${proposal.authorityDecision.reason ?? 'no reason'}`);
+    }
+    if (proposal.expiresAt !== undefined && now > proposal.expiresAt) {
+        errors.push('proposal has expired');
+    }
+    return errors;
+}

package/dist/ids.d.ts

@@ -0,0 +1,13 @@
+export declare function computeActionProposalId(params: {
+    kind: string;
+    parameters: Record<string, unknown>;
+    context: Record<string, unknown>;
+    proposedAt: number;
+}): string;
+export declare function computeActionExecutionId(proposalId: string): string;
+export declare function computeCommitmentHash(proposal: {
+    kind: string;
+    parameters: Record<string, unknown>;
+    context: Record<string, unknown>;
+}): string;
+export declare function computeReceiptId(executionId: string, proposalId: string): string;

package/dist/ids.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeActionProposalId = computeActionProposalId;
+exports.computeActionExecutionId = computeActionExecutionId;
+exports.computeCommitmentHash = computeCommitmentHash;
+exports.computeReceiptId = computeReceiptId;
+const canonical_js_1 = require("./canonical.js");
+function computeActionProposalId(params) {
+    return 'totem:ia:proposal:' + (0, canonical_js_1.hashCanonical)('TOTEM_INDUSTRIAL_ACTION_PROPOSAL_V1', {
+        kind: params.kind,
+        parameters: params.parameters,
+        context: params.context,
+        proposedAt: params.proposedAt,
+    });
+}
+function computeActionExecutionId(proposalId) {
+    return 'totem:ia:exec:' + (0, canonical_js_1.hashCanonical)('TOTEM_INDUSTRIAL_ACTION_EXECUTION_V1', {
+        proposalId,
+    });
+}
+function computeCommitmentHash(proposal) {
+    return (0, canonical_js_1.hashCanonical)('TOTEM_INDUSTRIAL_ACTION_COMMITMENT_V1', {
+        kind: proposal.kind,
+        parameters: proposal.parameters,
+        context: proposal.context,
+    });
+}
+function computeReceiptId(executionId, proposalId) {
+    return 'totem:ia:receipt:' + (0, canonical_js_1.hashCanonical)('TOTEM_INDUSTRIAL_ACTION_RECEIPT_V1', {
+        executionId,
+        proposalId,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type { ActionStatus, ExecutionStatus, ParameterType, ParameterSchema, ContextField, ContextSchema, ActionSchema, ActionError, ActionProposal, ActionExecution, ActionReceipt, ActionHandler, IndustrialActionDefinition, Condition, ConditionResult, ActionExecutor, GovernanceBridge, ActionStorage, CreateProposalParams, ExecuteActionResult, } from './types.js';
+export { toHex, canonicalJson, hashCanonical } from './canonical.js';
+export { computeActionProposalId, computeActionExecutionId, computeCommitmentHash, computeReceiptId, } from './ids.js';
+export { IndustrialActionError, ActionDefinitionError, ActionValidationError, ActionExecutionError, ActionConditionError, ActionGovernanceError, ActionCommitmentError, } from './errors.js';
+export { createActionDefinition, validateParameters, validateContext, assertValidParameters, assertValidContext, } from './definition.js';
+export { createProposal, verifyCommitment, assertValidProposal, isProposalExpired, isProposalExecutable, } from './proposal.js';
+export { createCommitment, verifyCommitmentBinding, serializeCommitmentPayload, } from './commitment.js';
+export { evaluateConditions, createCondition, } from './condition.js';
+export { executeAction, } from './executor.js';
+export { ActionRegistry } from './registry.js';
+export { createGovernanceBridge, checkGovernanceConstraints, } from './governance-bridge.js';
+export { createReceipt, verifyReceiptIntegrity, } from './receipt.js';

package/dist/index.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyReceiptIntegrity = exports.createReceipt = exports.checkGovernanceConstraints = exports.createGovernanceBridge = exports.ActionRegistry = exports.executeAction = exports.createCondition = exports.evaluateConditions = exports.serializeCommitmentPayload = exports.verifyCommitmentBinding = exports.createCommitment = exports.isProposalExecutable = exports.isProposalExpired = exports.assertValidProposal = exports.verifyCommitment = exports.createProposal = exports.assertValidContext = exports.assertValidParameters = exports.validateContext = exports.validateParameters = exports.createActionDefinition = exports.ActionCommitmentError = exports.ActionGovernanceError = exports.ActionConditionError = exports.ActionExecutionError = exports.ActionValidationError = exports.ActionDefinitionError = exports.IndustrialActionError = exports.computeReceiptId = exports.computeCommitmentHash = exports.computeActionExecutionId = exports.computeActionProposalId = exports.hashCanonical = exports.canonicalJson = exports.toHex = void 0;
+var canonical_js_1 = require("./canonical.js");
+Object.defineProperty(exports, "toHex", { enumerable: true, get: function () { return canonical_js_1.toHex; } });
+Object.defineProperty(exports, "canonicalJson", { enumerable: true, get: function () { return canonical_js_1.canonicalJson; } });
+Object.defineProperty(exports, "hashCanonical", { enumerable: true, get: function () { return canonical_js_1.hashCanonical; } });
+var ids_js_1 = require("./ids.js");
+Object.defineProperty(exports, "computeActionProposalId", { enumerable: true, get: function () { return ids_js_1.computeActionProposalId; } });
+Object.defineProperty(exports, "computeActionExecutionId", { enumerable: true, get: function () { return ids_js_1.computeActionExecutionId; } });
+Object.defineProperty(exports, "computeCommitmentHash", { enumerable: true, get: function () { return ids_js_1.computeCommitmentHash; } });
+Object.defineProperty(exports, "computeReceiptId", { enumerable: true, get: function () { return ids_js_1.computeReceiptId; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "IndustrialActionError", { enumerable: true, get: function () { return errors_js_1.IndustrialActionError; } });
+Object.defineProperty(exports, "ActionDefinitionError", { enumerable: true, get: function () { return errors_js_1.ActionDefinitionError; } });
+Object.defineProperty(exports, "ActionValidationError", { enumerable: true, get: function () { return errors_js_1.ActionValidationError; } });
+Object.defineProperty(exports, "ActionExecutionError", { enumerable: true, get: function () { return errors_js_1.ActionExecutionError; } });
+Object.defineProperty(exports, "ActionConditionError", { enumerable: true, get: function () { return errors_js_1.ActionConditionError; } });
+Object.defineProperty(exports, "ActionGovernanceError", { enumerable: true, get: function () { return errors_js_1.ActionGovernanceError; } });
+Object.defineProperty(exports, "ActionCommitmentError", { enumerable: true, get: function () { return errors_js_1.ActionCommitmentError; } });
+var definition_js_1 = require("./definition.js");
+Object.defineProperty(exports, "createActionDefinition", { enumerable: true, get: function () { return definition_js_1.createActionDefinition; } });
+Object.defineProperty(exports, "validateParameters", { enumerable: true, get: function () { return definition_js_1.validateParameters; } });
+Object.defineProperty(exports, "validateContext", { enumerable: true, get: function () { return definition_js_1.validateContext; } });
+Object.defineProperty(exports, "assertValidParameters", { enumerable: true, get: function () { return definition_js_1.assertValidParameters; } });
+Object.defineProperty(exports, "assertValidContext", { enumerable: true, get: function () { return definition_js_1.assertValidContext; } });
+var proposal_js_1 = require("./proposal.js");
+Object.defineProperty(exports, "createProposal", { enumerable: true, get: function () { return proposal_js_1.createProposal; } });
+Object.defineProperty(exports, "verifyCommitment", { enumerable: true, get: function () { return proposal_js_1.verifyCommitment; } });
+Object.defineProperty(exports, "assertValidProposal", { enumerable: true, get: function () { return proposal_js_1.assertValidProposal; } });
+Object.defineProperty(exports, "isProposalExpired", { enumerable: true, get: function () { return proposal_js_1.isProposalExpired; } });
+Object.defineProperty(exports, "isProposalExecutable", { enumerable: true, get: function () { return proposal_js_1.isProposalExecutable; } });
+var commitment_js_1 = require("./commitment.js");
+Object.defineProperty(exports, "createCommitment", { enumerable: true, get: function () { return commitment_js_1.createCommitment; } });
+Object.defineProperty(exports, "verifyCommitmentBinding", { enumerable: true, get: function () { return commitment_js_1.verifyCommitmentBinding; } });
+Object.defineProperty(exports, "serializeCommitmentPayload", { enumerable: true, get: function () { return commitment_js_1.serializeCommitmentPayload; } });
+var condition_js_1 = require("./condition.js");
+Object.defineProperty(exports, "evaluateConditions", { enumerable: true, get: function () { return condition_js_1.evaluateConditions; } });
+Object.defineProperty(exports, "createCondition", { enumerable: true, get: function () { return condition_js_1.createCondition; } });
+var executor_js_1 = require("./executor.js");
+Object.defineProperty(exports, "executeAction", { enumerable: true, get: function () { return executor_js_1.executeAction; } });
+var registry_js_1 = require("./registry.js");
+Object.defineProperty(exports, "ActionRegistry", { enumerable: true, get: function () { return registry_js_1.ActionRegistry; } });
+var governance_bridge_js_1 = require("./governance-bridge.js");
+Object.defineProperty(exports, "createGovernanceBridge", { enumerable: true, get: function () { return governance_bridge_js_1.createGovernanceBridge; } });
+Object.defineProperty(exports, "checkGovernanceConstraints", { enumerable: true, get: function () { return governance_bridge_js_1.checkGovernanceConstraints; } });
+var receipt_js_1 = require("./receipt.js");
+Object.defineProperty(exports, "createReceipt", { enumerable: true, get: function () { return receipt_js_1.createReceipt; } });
+Object.defineProperty(exports, "verifyReceiptIntegrity", { enumerable: true, get: function () { return receipt_js_1.verifyReceiptIntegrity; } });

package/dist/proposal.d.ts

@@ -0,0 +1,6 @@
+import type { CreateProposalParams, ActionProposal } from './types.js';
+export declare function createProposal(params: CreateProposalParams): ActionProposal;
+export declare function verifyCommitment(proposal: ActionProposal): boolean;
+export declare function assertValidProposal(proposal: ActionProposal): void;
+export declare function isProposalExpired(proposal: ActionProposal, now: number): boolean;
+export declare function isProposalExecutable(proposal: ActionProposal, now: number): boolean;

package/dist/proposal.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProposal = createProposal;
+exports.verifyCommitment = verifyCommitment;
+exports.assertValidProposal = assertValidProposal;
+exports.isProposalExpired = isProposalExpired;
+exports.isProposalExecutable = isProposalExecutable;
+const errors_js_1 = require("./errors.js");
+const ids_js_1 = require("./ids.js");
+function createProposal(params) {
+    const now = params.proposedAt ?? Date.now();
+    const commitmentHash = (0, ids_js_1.computeCommitmentHash)({
+        kind: params.kind,
+        parameters: params.parameters,
+        context: params.context,
+    });
+    const id = (0, ids_js_1.computeActionProposalId)({
+        kind: params.kind,
+        parameters: params.parameters,
+        context: params.context,
+        proposedAt: now,
+    });
+    const proposal = {
+        id,
+        kind: params.kind,
+        parameters: params.parameters,
+        context: params.context,
+        proposedAt: now,
+        commitmentHash,
+    };
+    if (params.expiresAt !== undefined)
+        proposal.expiresAt = params.expiresAt;
+    if (params.mandateProofId !== undefined)
+        proposal.mandateProofId = params.mandateProofId;
+    return proposal;
+}
+function verifyCommitment(proposal) {
+    const expected = (0, ids_js_1.computeCommitmentHash)({
+        kind: proposal.kind,
+        parameters: proposal.parameters,
+        context: proposal.context,
+    });
+    return proposal.commitmentHash === expected;
+}
+function assertValidProposal(proposal) {
+    if (!proposal.id)
+        throw new errors_js_1.ActionValidationError('proposal id is required');
+    if (!proposal.kind)
+        throw new errors_js_1.ActionValidationError('proposal kind is required');
+    if (!verifyCommitment(proposal)) {
+        throw new errors_js_1.ActionCommitmentError('commitment hash mismatch');
+    }
+}
+function isProposalExpired(proposal, now) {
+    if (proposal.expiresAt === undefined)
+        return false;
+    return now > proposal.expiresAt;
+}
+function isProposalExecutable(proposal, now) {
+    if (isProposalExpired(proposal, now))
+        return false;
+    if (proposal.authorityDecision && !proposal.authorityDecision.allowed)
+        return false;
+    return true;
+}

package/dist/receipt.d.ts

@@ -0,0 +1,17 @@
+import type { ActionReceipt } from './types.js';
+export declare function createReceipt(params: {
+    actionId: string;
+    proposalId: string;
+    kind: string;
+    status: ActionReceipt['status'];
+    commitmentHash: string;
+    parameters: Record<string, unknown>;
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+    issuedAt?: number;
+}): ActionReceipt;
+export declare function verifyReceiptIntegrity(receipt: ActionReceipt): boolean;

package/dist/receipt.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReceipt = createReceipt;
+exports.verifyReceiptIntegrity = verifyReceiptIntegrity;
+const ids_js_1 = require("./ids.js");
+function createReceipt(params) {
+    const receiptId = (0, ids_js_1.computeReceiptId)(params.actionId, params.proposalId);
+    return {
+        receiptId,
+        actionId: params.actionId,
+        proposalId: params.proposalId,
+        kind: params.kind,
+        status: params.status,
+        commitmentHash: params.commitmentHash,
+        parameters: params.parameters,
+        result: params.result,
+        error: params.error,
+        issuedAt: params.issuedAt ?? Date.now(),
+    };
+}
+function verifyReceiptIntegrity(receipt) {
+    const expectedId = (0, ids_js_1.computeReceiptId)(receipt.actionId, receipt.proposalId);
+    return receipt.receiptId === expectedId;
+}

package/dist/registry.d.ts

@@ -0,0 +1,14 @@
+import type { IndustrialActionDefinition, ActionExecutor } from './types.js';
+export declare class ActionRegistry {
+    private definitions;
+    private executors;
+    registerDefinition(definition: IndustrialActionDefinition): void;
+    registerExecutor(executor: ActionExecutor): void;
+    getDefinition(kind: string): IndustrialActionDefinition | undefined;
+    getExecutor(kind: string): ActionExecutor | undefined;
+    getDefinitionOrThrow(kind: string): IndustrialActionDefinition;
+    getExecutorOrThrow(kind: string): ActionExecutor;
+    hasDefinition(kind: string): boolean;
+    hasExecutor(kind: string): boolean;
+    listKinds(): string[];
+}

package/dist/registry.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionRegistry = void 0;
+const errors_js_1 = require("./errors.js");
+class ActionRegistry {
+    constructor() {
+        this.definitions = new Map();
+        this.executors = new Map();
+    }
+    registerDefinition(definition) {
+        if (this.definitions.has(definition.kind)) {
+            throw new errors_js_1.ActionDefinitionError(`definition '${definition.kind}' is already registered`);
+        }
+        this.definitions.set(definition.kind, definition);
+    }
+    registerExecutor(executor) {
+        if (this.executors.has(executor.kind)) {
+            throw new errors_js_1.ActionDefinitionError(`executor '${executor.kind}' is already registered`);
+        }
+        this.executors.set(executor.kind, executor);
+    }
+    getDefinition(kind) {
+        return this.definitions.get(kind);
+    }
+    getExecutor(kind) {
+        return this.executors.get(kind);
+    }
+    getDefinitionOrThrow(kind) {
+        const def = this.definitions.get(kind);
+        if (!def)
+            throw new errors_js_1.ActionDefinitionError(`no definition registered for '${kind}'`);
+        return def;
+    }
+    getExecutorOrThrow(kind) {
+        const exec = this.executors.get(kind);
+        if (!exec)
+            throw new errors_js_1.ActionDefinitionError(`no executor registered for '${kind}'`);
+        return exec;
+    }
+    hasDefinition(kind) {
+        return this.definitions.has(kind);
+    }
+    hasExecutor(kind) {
+        return this.executors.has(kind);
+    }
+    listKinds() {
+        return Array.from(this.definitions.keys());
+    }
+}
+exports.ActionRegistry = ActionRegistry;

package/dist/types.d.ts

@@ -0,0 +1,121 @@
+import type { AuthorityDecision } from '@totemsdk/authority';
+import type { EdgeOperationResult } from '@totemsdk/edge';
+export type ActionStatus = 'proposed' | 'approved' | 'reserved' | 'executing' | 'confirmed' | 'failed' | 'unknown' | 'cancelled';
+export type ExecutionStatus = 'pending' | 'executing' | 'confirmed' | 'failed' | 'unknown';
+export type ParameterType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+export interface ParameterSchema {
+    name: string;
+    type: ParameterType;
+    required: boolean;
+    description?: string;
+    defaultValue?: unknown;
+    validation?: (value: unknown) => string | null;
+}
+export interface ContextField {
+    name: string;
+    value: unknown;
+    timestamp: number;
+    source?: string;
+}
+export interface ContextSchema {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'object';
+    required: boolean;
+    description?: string;
+    maxAgeMs?: number;
+}
+export interface ActionSchema {
+    parameters: ParameterSchema[];
+    context: ContextSchema[];
+}
+export interface ActionError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface ActionProposal {
+    id: string;
+    kind: string;
+    parameters: Record<string, unknown>;
+    context: Record<string, unknown>;
+    proposedAt: number;
+    expiresAt?: number;
+    commitmentHash: string;
+    mandateProofId?: string;
+    authorityDecision?: AuthorityDecision;
+}
+export interface ActionExecution {
+    id: string;
+    proposalId: string;
+    status: ExecutionStatus;
+    result?: unknown;
+    error?: ActionError;
+    startedAt: number;
+    completedAt?: number;
+    receipt?: ActionReceipt;
+}
+export interface ActionReceipt {
+    receiptId: string;
+    actionId: string;
+    proposalId: string;
+    kind: string;
+    status: ActionStatus;
+    commitmentHash: string;
+    parameters: Record<string, unknown>;
+    result?: unknown;
+    error?: ActionError;
+    issuedAt: number;
+}
+export interface ActionHandler<TParameters = unknown, TResult = unknown> {
+    execute(params: TParameters, context: Record<string, unknown>): Promise<EdgeOperationResult<TResult>>;
+}
+export interface IndustrialActionDefinition<TParameters = unknown, TResult = unknown> {
+    kind: string;
+    description: string;
+    schema: ActionSchema;
+    handler: ActionHandler<TParameters, TResult>;
+}
+export interface Condition {
+    type: 'parameter_range' | 'context_match' | 'time_window' | 'custom';
+    field?: string;
+    operator?: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in';
+    value?: unknown;
+    evaluate?: (params: Record<string, unknown>, context: Record<string, unknown>) => string | null;
+}
+export interface ConditionResult {
+    passed: boolean;
+    failed: Array<{
+        condition: Condition;
+        reason: string;
+    }>;
+}
+export interface ActionExecutor<TParameters = unknown, TResult = unknown> {
+    kind: string;
+    execute(proposal: ActionProposal, params: TParameters, context: Record<string, unknown>): Promise<EdgeOperationResult<TResult>>;
+}
+export interface GovernanceBridge {
+    reserve(proposal: ActionProposal, mandateProofId: string): Promise<EdgeOperationResult<{
+        reservationId: string;
+    }>>;
+    commit(reservationId: string, execution: ActionExecution): Promise<EdgeOperationResult<void>>;
+    abort(reservationId: string, error: ActionError): Promise<EdgeOperationResult<void>>;
+}
+export interface ActionStorage {
+    saveProposal(proposal: ActionProposal): Promise<EdgeOperationResult<void>>;
+    getProposal(id: string): Promise<EdgeOperationResult<ActionProposal>>;
+    saveExecution(execution: ActionExecution): Promise<EdgeOperationResult<void>>;
+    getExecution(id: string): Promise<EdgeOperationResult<ActionExecution>>;
+    saveReceipt(receipt: ActionReceipt): Promise<EdgeOperationResult<void>>;
+}
+export interface CreateProposalParams {
+    kind: string;
+    parameters: Record<string, unknown>;
+    context: Record<string, unknown>;
+    proposedAt?: number;
+    expiresAt?: number;
+    mandateProofId?: string;
+}
+export interface ExecuteActionResult<TResult = unknown> {
+    execution: ActionExecution;
+    receipt?: ActionReceipt;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@totemsdk/industrial-action",
+  "version": "0.1.0",
+  "description": "Deterministic industrial action lifecycle for Totem Edge — converts governed intent into context-aware, bounded, verifiably executed operations on field devices and protocols",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "",
+    "clean": "rm -rf dist",
+    "test": "jest --passWithNoTests"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@totemsdk/core": "^1.1.0",
+    "@totemsdk/proof": "^0.1.2",
+    "@totemsdk/authority": "^0.1.2",
+    "@totemsdk/edge": "^0.1.3"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^30.4.2",
+    "jest-environment-node": "^30.0.0",
+    "jest-runtime": "^30.0.0",
+    "@swc/core": "^1.15.46",
+    "@swc/jest": "^0.2.39",
+    "ts-jest": "^29.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Totem SDK",
+  "homepage": "https://totem.ing",
+  "bugs": {
+    "url": "https://github.com/totem-sdk/totem-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/totem-sdk/totem-sdk.git",
+    "directory": "packages/totem-sdk/packages/industrial-action"
+  },
+  "keywords": [
+    "totem",
+    "totemsdk",
+    "industrial",
+    "iot",
+    "edge",
+    "action",
+    "operational",
+    "opcua",
+    "modbus",
+    "bacnet",
+    "guardrails"
+  ]
+}