@melra/runtime-core 0.3.0-alpha.14 → 0.3.0-alpha.16

package/README.md

@@ -17,7 +17,8 @@ under an `AbortSignal` armed with the duration budget, then verifies.
 Verification decides success, not the adapter. A task reaches
 `verified_success` only when the adapter succeeded *and* every declared evidence
 predicate passed; an adapter that reported success with failing evidence is
-`partial`. Retries apply to `read` effects only — mutations and destructive
+`partial`, unless the only unmet evidence is a `semantic` question, which waits
+in `waiting_user` and settles closed at expiry (#54). Retries apply to `read` effects only — mutations and destructive
 operations run at most once, because a retried delete is a second delete.
 
 `WorkflowController` layers a bounded graph over that same pipeline. Nine node
@@ -40,7 +41,7 @@ Workflow durability, briefly:
 - Definitions and adapter results are sealed with AES-256-GCM bound to record
   identity and purpose.
 
-Requires Node.js 22 or newer. Full documentation:
+Requires Node.js 22.13 or newer, or 23.4 or newer. Full documentation:
 [github.com/XAGI-Lab/melra](https://github.com/XAGI-Lab/melra)
 
 Apache-2.0

package/dist/task-controller.d.ts

@@ -25,6 +25,16 @@ export interface TaskPlanOptions {
      */
     stored?: boolean;
 }
+/**
+ * Fill in `requiredEvidence` for a mutation that declared none.
+ *
+ * Applied once, where the request is normalized, so the derived predicates flow
+ * identically into the policy decision, the sealed payload, the persisted task
+ * record, and verification. A caller that declared its own evidence is left
+ * untouched — this only replaces an empty list. Exported for `melra policy
+ * test`, whose preview must decide on the request the server would.
+ */
+export declare function withDefaultEvidence(request: TaskRequest): TaskRequest;
 /**
  * A grant's durable draw-down, the way policy wants to read it.
  *
@@ -40,6 +50,8 @@ export declare class TaskController {
     private readonly verifier;
     private readonly payloadCipher;
     private readonly active;
+    /** Each task running here, settled once it has ended (see `settled`). */
+    private readonly running;
     private readonly breaker;
     /** Whether approvals come only from an operator, out of band. */
     get enforced(): boolean;
@@ -55,10 +67,12 @@ export declare class TaskController {
     private readonly capabilityUsage;
     /**
      * Draws by tasks between their re-check and their record, per grant and
-     * task. The durable draw is written only once work is verified, so without
-     * this two tasks running at once both saw the grant unspent: two operations
-     * against `maxOperations: 1`, a parallel workflow node overspending
-     * `dailyMax`.
+     * task. The durable draw is written only once the adapter has answered, so
+     * without this two tasks running at once both saw the grant unspent: two
+     * operations against `maxOperations: 1`, a parallel workflow node
+     * overspending `dailyMax`. Let go once the draw is written or the effect is
+     * known not to have run; one whose draw failed to write is held until
+     * recovery writes it (`drawGrant`).
      *
      * ponytail: held in this process. Two servers sharing one database can
      * still both pass a re-check at the same moment; a durable reservation row
@@ -71,9 +85,25 @@ export declare class TaskController {
     preflight(request: TaskRequest, options?: {
         stored?: boolean;
     }): PolicyDecision;
+    /** Refuses a predicate no registered verifier can check, or that it would refuse to. */
+    assertVerifiable(predicates: EvidencePredicate[], options?: {
+        stored?: boolean;
+    }): void;
     status(taskId: string): TaskRecord;
     execute(taskId: string, approval?: ApprovalResponse): Promise<ExecutionResult>;
+    /**
+     * Resolves once a task this controller is running has ended, its outcome
+     * recorded: a cancel only signals the adapter to stop. At once for one it
+     * is not running.
+     */
+    settled(taskId: string): Promise<void>;
     cancel(taskId: string): TaskRecord;
+    /**
+     * Writes a task out of planned or awaiting_approval, unless a deny or an
+     * execute in another process got there after this one read it: that one
+     * stands, and this one is refused as it would have been had it read later.
+     */
+    private leaveUnstarted;
     verifyPersisted(taskId: string, predicates: EvidencePredicate[]): Promise<{
         verified: boolean;
         evidence: EvidenceItem[];
@@ -96,6 +126,16 @@ export declare class TaskController {
      * provider could not be reached and the task stays exactly where it was.
      */
     reconcile(taskId: string): Promise<ExecutionResult>;
+    /**
+     * Writes a reconcile's answer in one transaction, and only while the task
+     * still waits for one. Two reconciles of one task (two melra_execute calls,
+     * or the sweep's recovery beside an agent's) each read it parked and ask
+     * the provider; written unconditionally, the slower answer, even one that
+     * could not reach the provider, overwrote a settle the other had recorded
+     * and dropped its receipt. Now the first stands, and the other writes
+     * nothing, not even a receipt, and returns the task as it now stands.
+     */
+    private settleParked;
     /**
      * Settle a task as done on evidence gathered after the fact.
      *
@@ -105,11 +145,51 @@ export declare class TaskController {
      * or an effect settled this way would be free to run again and free to spend.
      */
     private resolveAsVerified;
+    /**
+     * Draws the grant behind an effect already done, once per task however
+     * often asked. Policy is read for the grant id only: this is accounting
+     * rather than permission, so a grant that has since run out still pays for
+     * what it authorised. Asked as if nothing were drawn, because policy names
+     * no grant at all for one that is now exhausted, and the effect then went
+     * uncharged. A task that drew one already is left alone: policy read now
+     * names the first grant that matches, not the one execute drew once that
+     * was spent, and charging it too drew the task twice. Drawn, it lets go
+     * of a reservation `execute` held when its own draw failed to write.
+     */
+    private drawGrant;
+    /**
+     * Settle a task whose idempotency key is committed to it. A key is
+     * committed only once every kernel check held, so whatever stopped the
+     * task came after the effect: an interruption, or a write that failed. One
+     * with a semantic question commits on entering `waiting_user`, so its
+     * commit never says the question was answered: it settles closed, as at
+     * expiry (#54).
+     */
+    private settleCommitted;
     /**
      * With `failed`, each task that could not be recovered is recorded there by
      * id instead of the first failure being thrown at the end.
      */
     recoverInterrupted(failed?: Map<string, unknown>): Promise<TaskRecord[]>;
+    /**
+     * A waiting task whose judgements are past their `expiresAt` settles
+     * closed. Re-read and written in one transaction, so a peer settling the
+     * same task wins once.
+     *
+     * ponytail: runs on the startup pass and the 30 s recovery sweep, so a wait
+     * can outlive its `expiresAt` by one interval, or until a runtime next opens
+     * this data directory; a verdict tool must check `expiresAt` itself.
+     */
+    private expireJudgements;
+    /**
+     * No answer is not a yes (#54). A task whose semantic question went
+     * unanswered, at expiry or cut off after its commit, settles closed: its
+     * effect ran, so a change is `recovery_required` (never `failed`) and a
+     * read is `partial`. Nothing runs here, so it writes no receipt: the
+     * certificate, replaced, carries the evidence of the task's last one, the
+     * live path's or the one recovery wrote.
+     */
+    private settleUnanswered;
     private recoverTask;
     /**
      * What an approver is shown: the effect contract, minus the challenge and
@@ -163,6 +243,16 @@ export declare class TaskController {
         receipts: ActionReceipt[];
         certificate?: ExecutionCertificate;
     };
+    /**
+     * A task's certificate, written now for a `verified_success` task whose
+     * certificate failed to write after it was recorded: a workflow counts a
+     * step done only on its certificate. For a writer of the run, never a
+     * read. Only that status, because every other path to it writes the
+     * certificate before the task, and `execute`, which does not, writes it
+     * only if none is stored: whoever writes first, both hand out the same one.
+     * A write that fails again is left for the next writer.
+     */
+    certify(taskId: string): ExecutionCertificate | undefined;
     /**
      * The mode a task's effect ran under: recorded when it started running, or,
      * for a task that started before that was recorded, the mode on its first

package/dist/task-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-controller.d.ts","sourceRoot":"","sources":["../src/task-controller.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"task-controller.d.ts","sourceRoot":"","sources":["../src/task-controller.ts"],"names":[],"mappings":"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"}