@jinn-network/task-posting 0.0.0 → 0.1.0-canary.sha.786221faf848b3c859ddbc76fec09338df64d83b

package/README.md

@@ -1 +1,96 @@
-Placeholder. Real versions come from stack-npm-publish.yml.
+# @jinn-network/task-posting
+
+> Candidate in `implementations-v1`. Eligible for receipt-gated canary; that is not independent ratification.
+
+Supply policy for marketplace posting: which pool entries post, when, at what terms, under whose
+identity, with the escrow surfaced before spending.
+
+`planPosting(pool, policy)` is pure — a materialized pool listing plus a policy in, a
+`PostingPlan` out, carrying per-entry and total escrow. `executePosting(deps, plan)` surfaces that
+plan, requires approval before spending, and posts through an injected requester backend.
+Explicit post is the default; auto-post is an opt-in standing policy flag with the same visibility
+in a log line.
+
+The plan is the replay unit: the sealed dispatch Submission is a function of the plan alone, so
+re-executing the same plan produces byte-identical Submission bytes, the same broadcast-intent
+key, and a replayed outcome rather than a second post.
+
+## Requester posting boundary
+
+This package owns supply **policy** only. `PostingDeps.backend` is the existing
+`MarketplaceRequesterBackend` from `@jinn-network/marketplace-binding`. It owns exact Task and
+Submission admission, requester/idempotency scope, the posting WAL, recovered outcome
+reconciliation and the actual transaction. This package never receives raw chain configuration,
+wallet/broadcast ports, or a direct `postTask` function. The host must compose the backend with the
+same creator and terms used to construct the plan; those configured venue inputs do not cross the
+per-post operation boundary.
+
+`executePosting` calls `backend.post(taskBytes, submissionBytes)` only after the plan is surfaced,
+approval is granted and the complete batch passes its pure preflight. A recovered backend outcome
+is accepted exactly like the original result. A retryable unresolved operation is reported as
+uncertain and is never retried here; the host may invoke `backend.recoverPosting()` before a later
+policy run. No separate work-client package or wrapper is required.
+
+## Reported to the program: F-C5-8 (resolved — ruling R10)
+
+**The pool listing this package is pinned to consume is not `PostingPoolEntry`, and one field of
+`PostingPoolEntry` has no producer anywhere in the stack.** The C5 plan's Task B5 pins
+`(entry: PoolListing[number]) => PostingPoolEntry` and instructs a stop-and-report if it does not
+compile (program §5 contract 11). It does not compile. This is that report.
+
+The task-derivation `SupplyPool.list()` yields `PoolEntrySummary`:
+
+| `PostingPoolEntry` needs | C4 has |
+| --- | --- |
+| `taskBytes` | on `PoolEntry` via `SupplyPool.get()`, not on the listing element |
+| `admissionReceiptDigest` | the same value, named `receiptDigest` |
+| `evaluationSpecPublic` | not modelled — no package in the stack computes it |
+
+The plan's own pre-flight gate accepts the first row (it stops only when the pool exposes neither
+the bytes "or a way to read them" nor a per-entry receipt digest). The other two are unreconciled
+between C4's pool contract and spec §8's posting inputs.
+
+`evaluationSpecPublic` is the load-bearing one: it is the sole gate implementing D5 ("v1 posts
+public-specification evaluation legs only") in both `planPosting` (the `evaluation-not-public`
+skip) and `buildDispatchSubmission` (`assertPublicSpecEvaluationLeg`). A boolean nobody produces
+makes every D5 refusal a caller's claim rather than a fact about the sealed bytes.
+
+**What this package does.** `PostingPoolEntry` is untouched — it is exactly what the
+plan pins, and it was not widened. The reconciliation lives in one named, tested adapter,
+`postingPoolEntry(entry, options)`, which carries C4's `receiptDigest` into
+`admissionReceiptDigest` and **derives** `evaluationSpecPublic` from the sealed EvaluationSpec
+bytes the entry's own digest addresses: D5's stamping writes `accessClass: "public"` onto every
+access-classified descriptor at seal time, and `evaluationSpecIsPublic` reads those stamps back,
+failing closed on an unstamped specification, a private stamp, a non-string stamp, or bytes that
+are not a JSON document. `src/pool-shape.test.ts` is the package's sole, test-only dependency on
+task derivation; it pins C4's stored entry against the adapter input type at compile time, so a
+rename on either side stops the build.
+
+**How the program ruled (R10).** The C5 plan was wrong on every count; C4 is unchanged.
+
+1. **`receiptDigest` stays C4's name** — it is what the program pinned (§4, ruling R5). Posting
+   renames at its own boundary. The plan's alternative, renaming C4 to match the plan's guess,
+   would have churned a pinned interface to spare this package one adapter.
+2. **`evaluationSpecPublic` is derived here, permanently** — never modelled on the pool entry and
+   never carried. Deriving it from the sealed bytes is what makes a D5 refusal a fact about the
+   specification rather than a claim by whoever produced the entry; a carried boolean would be a
+   silent downgrade of the gate. `src/pool-shape.test.ts` pin (d) fails the build if any producer
+   grows such a field, and the fix in that case is to keep deriving, not to start trusting it.
+3. **The adapter stays on the public surface.** `postingPoolEntry`, `evaluationSpecIsPublic`, and
+   `SuppliedPoolEntry` are exported: the tier-4 composition is the only place holding both a pool
+   and this application, so it is the caller that needs them, and exporting the tested adapter is
+   what stops each composition from inventing a looser one. The program's §4 "C5 produces" list is
+   amended accordingly.
+
+The plan's Task B5 identity assertion is likewise amended: it pins the two-step join
+(`SupplyPool.get()` → `SuppliedPoolEntry` → `PostingPoolEntry`) rather than the listing element,
+because a listing that carried every pair's sealed bytes would be the wrong contract for a pool
+that exists to be enumerated cheaply.
+
+## What v1 does not do
+
+- No pricing engine — terms are operator-supplied (design §12).
+- No derivation, no admission, no attestation reading. Posting carries the admission receipt by
+  digest and never re-decides admission.
+- No private evaluation material: v1 posts public-specification evaluation legs only, and
+  `capabilityGrants` is never populated (design §8, D5).

package/dist/digest.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The one shape a record-body digest may take in this package: `sha256:` plus 64 lower-case hex
+ * characters (program §5 contract 6). Bare hex is the in-toto DigestSet form and the on-chain
+ * `bytes32` anchor form; the two are not interchangeable, and every conversion between them is
+ * explicit and checked at the point of conversion.
+ */
+export declare const PREFIXED_SHA256_PATTERN: RegExp;
+/**
+ * Fails closed on any digest that is not in the canonical prefixed form. Callers pass the field
+ * name so the refusal names the input the operator has to fix, not just its value.
+ */
+export declare function assertPrefixedSha256(digest: string, field: string): asserts digest is `sha256:${string}`;

package/dist/digest.js

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: MIT
+/**
+ * The one shape a record-body digest may take in this package: `sha256:` plus 64 lower-case hex
+ * characters (program §5 contract 6). Bare hex is the in-toto DigestSet form and the on-chain
+ * `bytes32` anchor form; the two are not interchangeable, and every conversion between them is
+ * explicit and checked at the point of conversion.
+ */
+export const PREFIXED_SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+/**
+ * Fails closed on any digest that is not in the canonical prefixed form. Callers pass the field
+ * name so the refusal names the input the operator has to fix, not just its value.
+ */
+export function assertPrefixedSha256(digest, field) {
+    if (!PREFIXED_SHA256_PATTERN.test(digest)) {
+        throw new Error(`${field} ${JSON.stringify(digest)} is not a sha256:-prefixed lower-case 64-hex digest`);
+    }
+}

package/dist/dispatch-submission.d.ts

@@ -0,0 +1,24 @@
+import type { PostingPlan, PostingPlanEntry, PostingPoolEntry } from "./types.js";
+/** Namespace for the identifiers derived below; part of the byte-stability contract. */
+export declare const POSTING_SUBMISSION_NAMESPACE: "jinn:task-posting:submission:v1";
+/**
+ * v1 posts public-specification evaluation legs only (design §8, D5). Grant hosting, minting, and
+ * redemption are non-goals (§12), so this package has no code path that populates
+ * `capabilityGrants` -- and refuses the entry that would need one rather than posting it with the
+ * private material silently dropped.
+ */
+export declare function assertPublicSpecEvaluationLeg(entry: PostingPoolEntry): void;
+/**
+ * Reads `attempts.maxTotal` back out of the bytes that were just sealed and holds it against the
+ * terms the escrow was computed from (finding F-C5-1's disposition: "half B seals
+ * `attempts.maxTotal` explicitly **and re-parses its own sealed bytes to assert agreement**").
+ *
+ * Comparing the plan's two in-memory numbers is a tautology. The gate that matters is over the
+ * bytes, because the requester backend takes the escrow multiplier from the sealed document
+ * (`submission.attempts?.maxTotal ?? 1`): a sealing layer that dropped, renamed, or coerced the
+ * field would send `(solution + verdict) x 1` to the chain while the surfaced plan and its log
+ * line said N. `assertMaxClaimsAgreement` throws on `undefined` precisely to make that fallback
+ * unreachable from here.
+ */
+export declare function assertSealedMaxClaimsAgreement(submissionBytes: Uint8Array, termsMaxClaims: number): void;
+export declare function buildDispatchSubmission(entry: PostingPoolEntry, planEntry: PostingPlanEntry, plan: PostingPlan): Uint8Array;

package/dist/dispatch-submission.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: MIT
+// The dispatch Submission a planned entry posts under. Every field is a function of the plan and
+// the entry -- no clock read, no random identifier -- because the broadcast-intent WAL is keyed on
+// `(creatorSafe, taskCidDigest, submissionDigest)`: a Submission that differed between two runs of
+// one plan would key a second intent and pay for a second post.
+import { ADMISSION_RECEIPT_ANNOTATION_URI, assertMaxClaimsAgreement, } from "@jinn-network/marketplace-binding";
+import { SubmissionRecordSchema, TASK_EXECUTION_PROTOCOL_URI, sealSubmission, sha256Hex, } from "@jinn-network/task-execution-protocol";
+import { PREFIXED_SHA256_PATTERN } from "./digest.js";
+/** Namespace for the identifiers derived below; part of the byte-stability contract. */
+export const POSTING_SUBMISSION_NAMESPACE = "jinn:task-posting:submission:v1";
+/**
+ * Record-body digests are `sha256:`-prefixed; in-toto DigestSet values are bare hex (program §5
+ * contract 6). This is the only conversion in this package that lands inside a document a
+ * requester pays to post, and nothing downstream re-checks it: TEP's `DigestMap` requires only
+ * non-empty keys, and the evaluation leg checks only that the admission-receipt descriptor is
+ * present and named. An unchecked `.slice()` here would seal `""`, `sha256:aaa...`, `AAA...`, or
+ * `zz` into an escrowed task and every later gate would still pass.
+ */
+function bareHex(digest, field) {
+    if (!PREFIXED_SHA256_PATTERN.test(digest)) {
+        throw new Error(`${field} ${JSON.stringify(digest)} is not a sha256:-prefixed lower-case 64-hex digest `
+            + "-- refusing to seal it into a Submission that is about to be posted and escrowed");
+    }
+    return digest.slice("sha256:".length);
+}
+/** 32 hex characters of a digest, shaped as a URN UUID (§8's `submission` identifier form). */
+function urnUuidFromHex(hex) {
+    return `urn:uuid:${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}`
+        + `-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+/**
+ * v1 posts public-specification evaluation legs only (design §8, D5). Grant hosting, minting, and
+ * redemption are non-goals (§12), so this package has no code path that populates
+ * `capabilityGrants` -- and refuses the entry that would need one rather than posting it with the
+ * private material silently dropped.
+ */
+export function assertPublicSpecEvaluationLeg(entry) {
+    if (entry.evaluationSpecPublic !== true) {
+        throw new Error(`${entry.taskDigest} declares a non-public evaluation specification; v1 posts `
+            + "public-specification evaluation legs only (design §8, D5)");
+    }
+}
+/**
+ * Reads `attempts.maxTotal` back out of the bytes that were just sealed and holds it against the
+ * terms the escrow was computed from (finding F-C5-1's disposition: "half B seals
+ * `attempts.maxTotal` explicitly **and re-parses its own sealed bytes to assert agreement**").
+ *
+ * Comparing the plan's two in-memory numbers is a tautology. The gate that matters is over the
+ * bytes, because the requester backend takes the escrow multiplier from the sealed document
+ * (`submission.attempts?.maxTotal ?? 1`): a sealing layer that dropped, renamed, or coerced the
+ * field would send `(solution + verdict) x 1` to the chain while the surfaced plan and its log
+ * line said N. `assertMaxClaimsAgreement` throws on `undefined` precisely to make that fallback
+ * unreachable from here.
+ */
+export function assertSealedMaxClaimsAgreement(submissionBytes, termsMaxClaims) {
+    const parsed = SubmissionRecordSchema.parse(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(submissionBytes)));
+    assertMaxClaimsAgreement(parsed.attempts?.maxTotal, termsMaxClaims);
+}
+export function buildDispatchSubmission(entry, planEntry, plan) {
+    assertPublicSpecEvaluationLeg(entry);
+    const receiptHex = bareHex(entry.admissionReceiptDigest, "admissionReceiptDigest");
+    const taskHex = sha256Hex(entry.taskBytes);
+    if (taskHex !== bareHex(entry.taskDigest, "taskDigest")) {
+        throw new Error(`pool entry ${entry.taskDigest} does not hash to its own bytes (sha256:${taskHex}) `
+            + "-- refusing to seal a Submission against a mismatched pair");
+    }
+    if (planEntry.maxClaims !== plan.terms.maxClaims) {
+        throw new Error(`plan entry maxClaims (${planEntry.maxClaims}) disagrees with the plan's terms `
+            + `(${plan.terms.maxClaims})`);
+    }
+    const seed = sha256Hex(new TextEncoder().encode(`${POSTING_SUBMISSION_NAMESPACE}|${entry.taskDigest}|${plan.requester}|${planEntry.deadline}`
+        + `|${planEntry.closeAt ?? ""}|${planEntry.maxClaims}`));
+    const submissionBytes = sealSubmission({
+        protocol: TASK_EXECUTION_PROTOCOL_URI,
+        submission: urnUuidFromHex(seed),
+        task: { digest: { sha256: taskHex } },
+        requester: plan.requester,
+        idempotencyKey: `${POSTING_SUBMISSION_NAMESPACE}:${entry.taskDigest}:${planEntry.deadline}`,
+        nonce: seed.slice(0, 32),
+        deadline: planEntry.deadline,
+        ...(planEntry.closeAt === undefined ? {} : { closeAt: planEntry.closeAt }),
+        attempts: { maxTotal: planEntry.maxClaims },
+        annotations: {
+            [ADMISSION_RECEIPT_ANNOTATION_URI]: {
+                name: "admission-receipt",
+                digest: { sha256: receiptHex },
+                ...(entry.admissionReceiptUri === undefined ? {} : { uri: entry.admissionReceiptUri }),
+            },
+        },
+    });
+    assertSealedMaxClaimsAgreement(submissionBytes, plan.terms.maxClaims);
+    return submissionBytes;
+}

package/dist/execute.d.ts

@@ -0,0 +1,54 @@
+import { type MarketplaceRequesterBackend } from "@jinn-network/marketplace-binding";
+import type { PostingPlan, PostingPoolEntry } from "./types.js";
+/** Shows the operator what is about to be spent. Rendering is the host's job, not this package's. */
+export interface PostingRenderPort {
+    renderPlan(plan: PostingPlan): void | Promise<void>;
+}
+export type PostingApproval = {
+    readonly approved: true;
+} | {
+    readonly approved: false;
+    readonly reason: string;
+};
+export interface PostingApprovalPort {
+    approvePlan(plan: PostingPlan): Promise<PostingApproval>;
+}
+export interface PostingLogLine {
+    readonly event: "posting.plan-surfaced" | "posting.auto-approved" | "posting.approved" | "posting.refused" | "posting.posted" | "posting.uncertain";
+    readonly fields: Readonly<Record<string, string>>;
+}
+/** Structured sink; this package never writes to an ambient console. */
+export interface PostingLogPort {
+    record(line: PostingLogLine): void;
+}
+export interface PostingDeps {
+    /** Task digest -> pool entry. The plan carries digests; the bytes are read here. */
+    readonly entries: ReadonlyMap<string, PostingPoolEntry>;
+    /**
+     * Sole authority for requester scope, posting WAL and recovered outcome reconciliation.
+     * The host composes it with the same creator and terms used to construct the plan.
+     */
+    readonly backend: MarketplaceRequesterBackend;
+    readonly render: PostingRenderPort;
+    readonly approval: PostingApprovalPort;
+    readonly log: PostingLogPort;
+}
+export interface PostingRunSummary {
+    readonly posted: readonly {
+        readonly taskDigest: `sha256:${string}`;
+        readonly taskId: bigint;
+        readonly txHash: `0x${string}`;
+    }[];
+    readonly uncertain: readonly {
+        readonly taskDigest: `sha256:${string}`;
+        readonly detail: string;
+    }[];
+    /** Set only when approval was withheld; the batch then spent nothing. */
+    readonly refused?: string;
+    readonly spentEscrowValueWei: bigint;
+}
+export declare class PostingRefusedError extends Error {
+    readonly reason: string;
+    constructor(reason: string, message: string);
+}
+export declare function executePosting(deps: PostingDeps, plan: PostingPlan): Promise<PostingRunSummary>;

package/dist/execute.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: MIT
+// Explicit post is the default (design §8): the plan -- terms and the computed escrow total -- is
+// surfaced before a wei is spent, and an approval decision is required. Auto-post is an opt-in
+// standing policy flag that pre-approves with THE SAME fields in a log line, so a standing policy
+// is never quieter than a hand-approved one (visible-money-actions).
+//
+// Everything that touches the chain is injected. The requester backend is the sole posting and
+// recovery authority; this package retains only selection, terms, approval, batching and logging.
+import { BroadcastUncertainError, postingEscrowValueWei, } from "@jinn-network/marketplace-binding";
+import { buildDispatchSubmission } from "./dispatch-submission.js";
+export class PostingRefusedError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "PostingRefusedError";
+    }
+}
+/** The money fields, identical for the explicit and the auto path. */
+function planFields(plan) {
+    return {
+        createdAt: plan.createdAt,
+        creatorSafe: plan.creatorSafe,
+        requester: plan.requester,
+        entries: String(plan.entries.length),
+        totalEscrowValueWei: String(plan.totalEscrowValueWei),
+        solutionMaxDeliveryRateWei: String(plan.terms.solutionMaxDeliveryRateWei),
+        verdictMaxDeliveryRateWei: String(plan.terms.verdictMaxDeliveryRateWei),
+        responseTimeoutSeconds: String(plan.terms.responseTimeoutSeconds),
+        maxClaims: String(plan.terms.maxClaims),
+        allowSolverSelfEvaluation: String(plan.terms.allowSolverSelfEvaluation),
+    };
+}
+/**
+ * Everything checkable about the batch, checked before the first wei leaves: the bytes for every
+ * planned digest are in hand, every entry's escrow is the escrow the plan's own terms imply, and
+ * every dispatch Submission seals. All three are pure, so a refusal raised from inside the post
+ * loop would only mean earlier entries were already posted and escrowed when it fired.
+ *
+ * The escrow re-derivation is the same class of check as the `maxClaims` gate one layer down:
+ * the requester backend computes the real `msg.value` from its configured terms and the sealed
+ * `attempts.maxTotal`. A plan carrying an understated `escrowValueWei` would render, log, and
+ * total a number that is not what the chain is sent.
+ */
+function prepareBatch(deps, plan) {
+    const expectedEscrowValueWei = postingEscrowValueWei(plan.terms);
+    return plan.entries.map((planEntry) => {
+        const entry = deps.entries.get(planEntry.taskDigest);
+        if (entry === undefined) {
+            throw new PostingRefusedError("pool-entry-missing", `planned entry ${planEntry.taskDigest} is not in the supplied pool -- refusing to post a `
+                + "batch whose bytes cannot be read");
+        }
+        if (planEntry.escrowValueWei !== expectedEscrowValueWei) {
+            throw new PostingRefusedError("escrow-disagrees-with-terms", `planned entry ${planEntry.taskDigest} carries escrow ${planEntry.escrowValueWei} wei, but `
+                + `this plan's terms imply ${expectedEscrowValueWei} wei -- the surfaced total would not `
+                + "be what is sent");
+        }
+        return { planEntry, entry, submissionBytes: buildDispatchSubmission(entry, planEntry, plan) };
+    });
+}
+function uncertainOperationDetail(error) {
+    if (error instanceof BroadcastUncertainError)
+        return error.message;
+    // MarketplaceRequesterBackend exposes operational failures through TaskExecutionBackend's
+    // error contract. Avoid a second runtime package edge just to recognize the generic shape.
+    if (error instanceof Error
+        && error.name === "TaskExecutionError"
+        && "category" in error
+        && error.category === "backend-unavailable"
+        && "retryable" in error
+        && error.retryable === true) {
+        const detail = "detail" in error ? error.detail : undefined;
+        return typeof detail === "string" ? detail : error.message;
+    }
+    return undefined;
+}
+export async function executePosting(deps, plan) {
+    await deps.render.renderPlan(plan);
+    deps.log.record({ event: "posting.plan-surfaced", fields: planFields(plan) });
+    if (plan.approval === "auto") {
+        deps.log.record({ event: "posting.auto-approved", fields: planFields(plan) });
+    }
+    else {
+        const decision = await deps.approval.approvePlan(plan);
+        if (!decision.approved) {
+            deps.log.record({
+                event: "posting.refused",
+                fields: { ...planFields(plan), reason: decision.reason },
+            });
+            return { posted: [], uncertain: [], refused: decision.reason, spentEscrowValueWei: 0n };
+        }
+        deps.log.record({ event: "posting.approved", fields: planFields(plan) });
+    }
+    // After the approval gate (a withheld plan is never inspected further) and before the first
+    // post: the whole batch is resolved and sealed, so a refusal cannot land mid-spend.
+    const prepared = prepareBatch(deps, plan);
+    const posted = [];
+    const uncertain = [];
+    let spentEscrowValueWei = 0n;
+    for (const { planEntry, entry, submissionBytes } of prepared) {
+        let outcome;
+        try {
+            // eslint-disable-next-line no-await-in-loop -- posts are sequential: one requester, one
+            // nonce sequence, and one escrow balance draining as the batch proceeds.
+            outcome = await deps.backend.post(entry.taskBytes, submissionBytes);
+        }
+        catch (error) {
+            const detail = uncertainOperationDetail(error);
+            if (detail !== undefined) {
+                // Never retried here: the requester backend resolves uncertain work through
+                // `recoverPosting()` and canonical evidence, not by posting again.
+                uncertain.push({ taskDigest: planEntry.taskDigest, detail });
+                deps.log.record({
+                    event: "posting.uncertain",
+                    fields: { taskDigest: planEntry.taskDigest, detail },
+                });
+                continue;
+            }
+            throw error;
+        }
+        posted.push({ taskDigest: planEntry.taskDigest, taskId: outcome.taskId, txHash: outcome.txHash });
+        spentEscrowValueWei += planEntry.escrowValueWei;
+        deps.log.record({
+            event: "posting.posted",
+            fields: {
+                taskDigest: planEntry.taskDigest,
+                taskId: String(outcome.taskId),
+                txHash: outcome.txHash,
+                escrowValueWei: String(planEntry.escrowValueWei),
+            },
+        });
+    }
+    return { posted, uncertain, spentEscrowValueWei };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { planPosting } from "./plan.js";
+export type { PostingPlan, PostingPlanEntry, PostingPolicy, PostingPoolEntry, PostingSkip, PostingSkipReason, } from "./types.js";
+export { POSTING_SUBMISSION_NAMESPACE, buildDispatchSubmission } from "./dispatch-submission.js";
+export { evaluationSpecIsPublic, postingPoolEntry } from "./pool-entry.js";
+export type { PostingPoolEntryOptions, SuppliedPoolEntry } from "./pool-entry.js";
+export { PostingRefusedError, executePosting } from "./execute.js";
+export type { PostingApproval, PostingApprovalPort, PostingDeps, PostingLogLine, PostingLogPort, PostingRenderPort, PostingRunSummary, } from "./execute.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+// @jinn-network/task-posting -- public surface.
+//
+// Policy in, posts out. `PostingDeps.backend` is the sole requester posting/recovery authority;
+// this package does not accept raw chain or binding ports.
+export { planPosting } from "./plan.js";
+export { POSTING_SUBMISSION_NAMESPACE, buildDispatchSubmission } from "./dispatch-submission.js";
+// The pool-shape reconciliation the program still has to rule on (README, F-C5-8): one named
+// adapter from what the supply pool stores to what this application posts, with D5's publicness
+// read off the sealed specification bytes instead of taken as a caller's claim.
+export { evaluationSpecIsPublic, postingPoolEntry } from "./pool-entry.js";
+export { PostingRefusedError, executePosting } from "./execute.js";

package/dist/order.d.ts

@@ -0,0 +1,6 @@
+/**
+ * UTF-16 code-unit ordering. `String.prototype.localeCompare` reads the host locale and the
+ * bundled ICU data, so it must never decide a batch's order: two hosts would plan two different
+ * batches from the same pool.
+ */
+export declare function compareCodeUnitStrings(left: string, right: string): number;

package/dist/order.js

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+/**
+ * UTF-16 code-unit ordering. `String.prototype.localeCompare` reads the host locale and the
+ * bundled ICU data, so it must never decide a batch's order: two hosts would plan two different
+ * batches from the same pool.
+ */
+export function compareCodeUnitStrings(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}

package/dist/plan.d.ts

@@ -0,0 +1,8 @@
+import type { PostingPlan, PostingPolicy, PostingPoolEntry } from "./types.js";
+/**
+ * Selects and orders the entries this batch posts.
+ *
+ * @param pool the materialized pool listing (finding F-C5-2: the caller reads `SupplyPool.list()`
+ * and passes the result; a pure function cannot await a store).
+ */
+export declare function planPosting(pool: readonly PostingPoolEntry[], policy: PostingPolicy): PostingPlan;

package/dist/plan.js

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: MIT
+// Supply policy, and nothing else (design §8, D6: production never posts; posting never derives).
+// Pure by construction: the plan is the replay unit, so every value the sealed Submission depends
+// on -- deadline, closeAt, maxClaims, requester -- is decided here and carried, never read from a
+// host clock at execution time.
+import { postingEscrowValueWei } from "@jinn-network/marketplace-binding";
+import { PREFIXED_SHA256_PATTERN } from "./digest.js";
+import { compareCodeUnitStrings } from "./order.js";
+function offsetIso(base, seconds) {
+    const parsed = Date.parse(base);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`policy.now must be an RFC 3339 timestamp with an offset, got ${base}`);
+    }
+    return new Date(parsed + seconds * 1_000).toISOString();
+}
+/**
+ * Both policy digest lists are membership-tested by exact string equality against `sha256:`-
+ * prefixed entry digests, so a list written in any other form matches nothing and the guard it was
+ * written for silently disarms: an excluded entry posts and its escrow is spent, and an
+ * already-posted entry is posted and escrowed a second time. Bare hex is the realistic mistake —
+ * it is the in-toto DigestSet form this stack writes elsewhere by law (program §5 contract 6) — so
+ * the list is validated rather than trusted, and a non-canonical entry fails the plan closed
+ * instead of quietly dropping out of the comparison.
+ */
+function digestSet(values, field) {
+    const digests = new Set();
+    for (const value of values ?? []) {
+        if (!PREFIXED_SHA256_PATTERN.test(value)) {
+            throw new Error(`policy.${field} entry ${JSON.stringify(value)} is not a sha256:-prefixed lower-case `
+                + "64-hex digest -- it would match no pool entry, so the batch would post and escrow the "
+                + "entry this list was written to hold back");
+        }
+        digests.add(value);
+    }
+    return digests;
+}
+/**
+ * Selects and orders the entries this batch posts.
+ *
+ * @param pool the materialized pool listing (finding F-C5-2: the caller reads `SupplyPool.list()`
+ * and passes the result; a pure function cannot await a store).
+ */
+export function planPosting(pool, policy) {
+    if (!Number.isInteger(policy.batchLimit) || policy.batchLimit < 1) {
+        throw new RangeError(`batchLimit must be a positive integer, got ${String(policy.batchLimit)}`);
+    }
+    if (!Number.isInteger(policy.deadlineSeconds) || policy.deadlineSeconds < 1) {
+        throw new RangeError(`deadlineSeconds must be a positive integer, got ${String(policy.deadlineSeconds)}`);
+    }
+    const deadline = offsetIso(policy.now, policy.deadlineSeconds);
+    const closeAt = policy.closeAtSeconds === undefined
+        ? undefined
+        : offsetIso(policy.now, policy.closeAtSeconds);
+    const excluded = digestSet(policy.excludedTaskDigests, "excludedTaskDigests");
+    const posted = digestSet(policy.postedTaskDigests, "postedTaskDigests");
+    const skipped = [];
+    const eligible = [];
+    for (const entry of pool) {
+        if (excluded.has(entry.taskDigest)) {
+            skipped.push({ taskDigest: entry.taskDigest, reason: "excluded" });
+            continue;
+        }
+        if (!entry.evaluationSpecPublic) {
+            skipped.push({ taskDigest: entry.taskDigest, reason: "evaluation-not-public" });
+            continue;
+        }
+        const repost = posted.has(entry.taskDigest);
+        if (repost && policy.repostPosted !== true) {
+            skipped.push({ taskDigest: entry.taskDigest, reason: "already-posted" });
+            continue;
+        }
+        eligible.push({ entry, repost });
+    }
+    // Never-posted first; within a group, code-unit order by digest so two hosts plan one batch.
+    eligible.sort((left, right) => {
+        if (left.repost !== right.repost)
+            return left.repost ? 1 : -1;
+        return compareCodeUnitStrings(left.entry.taskDigest, right.entry.taskDigest);
+    });
+    const entries = [];
+    for (const candidate of eligible) {
+        if (entries.length >= policy.batchLimit) {
+            skipped.push({ taskDigest: candidate.entry.taskDigest, reason: "batch-limit" });
+            continue;
+        }
+        entries.push({
+            taskDigest: candidate.entry.taskDigest,
+            deadline,
+            ...(closeAt === undefined ? {} : { closeAt }),
+            maxClaims: policy.terms.maxClaims,
+            escrowValueWei: postingEscrowValueWei(policy.terms),
+            repost: candidate.repost,
+        });
+    }
+    return {
+        createdAt: policy.now,
+        creatorSafe: policy.creatorSafe,
+        requester: policy.requester,
+        terms: policy.terms,
+        approval: policy.autoPost === true ? "auto" : "explicit",
+        entries,
+        totalEscrowValueWei: entries.reduce((total, planned) => total + planned.escrowValueWei, 0n),
+        skipped,
+    };
+}

package/dist/pool-entry.d.ts

@@ -0,0 +1,34 @@
+import type { PostingPoolEntry } from "./types.js";
+/**
+ * A pool entry as the supply pool stores it: the sealed pair's bytes, the digests that address
+ * them, and the digest of the admission receipt the pair earned.
+ */
+export interface SuppliedPoolEntry {
+    readonly taskDigest: `sha256:${string}`;
+    readonly taskBytes: Uint8Array;
+    readonly evaluationSpecDigest: `sha256:${string}`;
+    readonly evaluationSpecBytes: Uint8Array;
+    /** C4's name for the admission receipt this pair earned. */
+    readonly receiptDigest: `sha256:${string}`;
+}
+export interface PostingPoolEntryOptions {
+    /** Advisory acquisition hint for the receipt; the digest is what binds. */
+    readonly admissionReceiptUri?: string;
+}
+/**
+ * Whether every access-classified descriptor in a sealed EvaluationSpec is stamped public.
+ *
+ * A specification with no stamps at all is `false`: absence of a stamp is not evidence of
+ * publicness, and v1 posts public-specification evaluation legs only (design §8, D5). The walk is
+ * family-agnostic on purpose — it reads the stamps wherever a family block puts them rather than
+ * hard-coding one family's shape into the posting application.
+ */
+export declare function evaluationSpecIsPublic(evaluationSpecBytes: Uint8Array): boolean;
+/**
+ * Builds the entry this application posts from the entry the pool stores.
+ *
+ * Both digests are checked against the bytes they address before anything is read from those
+ * bytes: a publicness stamp read out of a specification the entry does not name would be a claim
+ * about some other document.
+ */
+export declare function postingPoolEntry(entry: SuppliedPoolEntry, options?: PostingPoolEntryOptions): PostingPoolEntry;

package/dist/pool-entry.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: MIT
+// The reconciliation between what C4's pool stores and what this application posts, filed as
+// F-C5-8 (see README, "Reported to the program"). C4's `PoolEntry` names the admission receipt
+// `receiptDigest` and models no publicness flag at all, while spec §8's D5 gate — the one
+// `planPosting` and `buildDispatchSubmission` both enforce — needs `admissionReceiptDigest` and
+// `evaluationSpecPublic`. Without this adapter the tier-4 composition would have to invent both,
+// and the D5 refusal would rest on a caller's assertion rather than on the sealed bytes.
+//
+// So `evaluationSpecPublic` is read here, off the EvaluationSpec bytes the entry's own digest
+// addresses: D5's stamping puts `accessClass: "public"` on every access-classified descriptor at
+// seal time, and this reads those stamps back. Fail closed in every direction — an unstamped
+// specification, a private stamp, a non-string stamp, or bytes that are not a JSON document all
+// yield `false`, which `planPosting` records as the `evaluation-not-public` skip.
+//
+// No runtime edge into `@jinn-network/task-derivation` (finding F-C5-5): the input is declared
+// structurally here and `pool-shape.test.ts` pins C4's stored entry against it at compile time.
+import { sha256Hex } from "@jinn-network/task-execution-protocol";
+import { assertPrefixedSha256 } from "./digest.js";
+const ACCESS_CLASS_KEY = "accessClass";
+const PUBLIC_ACCESS_CLASS = "public";
+function collectAccessClasses(node, found) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectAccessClasses(item, found);
+        return;
+    }
+    if (node === null || typeof node !== "object")
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        if (key === ACCESS_CLASS_KEY) {
+            found.push(value);
+            continue;
+        }
+        collectAccessClasses(value, found);
+    }
+}
+/**
+ * Whether every access-classified descriptor in a sealed EvaluationSpec is stamped public.
+ *
+ * A specification with no stamps at all is `false`: absence of a stamp is not evidence of
+ * publicness, and v1 posts public-specification evaluation legs only (design §8, D5). The walk is
+ * family-agnostic on purpose — it reads the stamps wherever a family block puts them rather than
+ * hard-coding one family's shape into the posting application.
+ */
+export function evaluationSpecIsPublic(evaluationSpecBytes) {
+    let document;
+    try {
+        document = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(evaluationSpecBytes));
+    }
+    catch {
+        return false;
+    }
+    const found = [];
+    collectAccessClasses(document, found);
+    if (found.length === 0)
+        return false;
+    return found.every((value) => value === PUBLIC_ACCESS_CLASS);
+}
+/**
+ * Builds the entry this application posts from the entry the pool stores.
+ *
+ * Both digests are checked against the bytes they address before anything is read from those
+ * bytes: a publicness stamp read out of a specification the entry does not name would be a claim
+ * about some other document.
+ */
+export function postingPoolEntry(entry, options = {}) {
+    assertPrefixedSha256(entry.taskDigest, "taskDigest");
+    assertPrefixedSha256(entry.evaluationSpecDigest, "evaluationSpecDigest");
+    assertPrefixedSha256(entry.receiptDigest, "receiptDigest");
+    const taskHex = sha256Hex(entry.taskBytes);
+    if (taskHex !== entry.taskDigest.slice("sha256:".length)) {
+        throw new Error(`pool entry taskDigest ${entry.taskDigest} does not address its bytes (sha256:${taskHex})`);
+    }
+    const specHex = sha256Hex(entry.evaluationSpecBytes);
+    if (specHex !== entry.evaluationSpecDigest.slice("sha256:".length)) {
+        throw new Error(`pool entry evaluationSpecDigest ${entry.evaluationSpecDigest} does not address its bytes `
+            + `(sha256:${specHex}) -- the access class read from those bytes would describe another `
+            + "specification");
+    }
+    return {
+        taskDigest: entry.taskDigest,
+        taskBytes: entry.taskBytes,
+        evaluationSpecDigest: entry.evaluationSpecDigest,
+        admissionReceiptDigest: entry.receiptDigest,
+        ...(options.admissionReceiptUri === undefined
+            ? {}
+            : { admissionReceiptUri: options.admissionReceiptUri }),
+        evaluationSpecPublic: evaluationSpecIsPublic(entry.evaluationSpecBytes),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+import type { DefaultPostingTerms } from "@jinn-network/marketplace-binding";
+/**
+ * One admitted, sealed pair as this application needs it. Structurally what C4's `SupplyPool`
+ * listing yields; declared here because §3.1 makes this package usable by "any requester with
+ * sealed pairs from any source", not only by C4's pool.
+ *
+ * `admissionReceiptDigest` is required: the dispatch Submission must carry the admission-receipt
+ * descriptor, or the evaluation leg derived from it later is refused (binding §7.39; plan finding
+ * F-C5-4).
+ */
+export interface PostingPoolEntry {
+    readonly taskDigest: `sha256:${string}`;
+    readonly taskBytes: Uint8Array;
+    readonly evaluationSpecDigest: `sha256:${string}`;
+    readonly admissionReceiptDigest: `sha256:${string}`;
+    readonly admissionReceiptUri?: string;
+    /** v1 posts public-specification evaluation legs only (design §8, D5); false is refused. */
+    readonly evaluationSpecPublic: boolean;
+}
+export type PostingSkipReason = "excluded" | "already-posted" | "batch-limit" | "evaluation-not-public";
+export interface PostingSkip {
+    readonly taskDigest: `sha256:${string}`;
+    readonly reason: PostingSkipReason;
+}
+/**
+ * Supply policy. `now` is an input, not a clock read: the sealed Submission is a function of the
+ * plan, so a plan built twice from the same inputs yields byte-identical bytes and therefore the
+ * same broadcast-intent key. A hidden clock would turn every replay into a new post.
+ */
+export interface PostingPolicy {
+    readonly terms: DefaultPostingTerms;
+    readonly creatorSafe: `0x${string}`;
+    /** The requester of record recorded in every Submission this plan seals. */
+    readonly requester: string;
+    /** RFC 3339 with an explicit offset. */
+    readonly now: string;
+    readonly deadlineSeconds: number;
+    readonly closeAtSeconds?: number;
+    readonly batchLimit: number;
+    readonly excludedTaskDigests?: readonly string[];
+    /** Digests already posted by this requester; never-posted entries always plan first. */
+    readonly postedTaskDigests?: readonly string[];
+    /** Default false: an already-posted entry is dropped, not merely deprioritized. */
+    readonly repostPosted?: boolean;
+    /** Opt-in standing approval. The plan still renders and still logs its terms and escrow. */
+    readonly autoPost?: boolean;
+}
+export interface PostingPlanEntry {
+    readonly taskDigest: `sha256:${string}`;
+    readonly deadline: string;
+    readonly closeAt?: string;
+    readonly maxClaims: number;
+    readonly escrowValueWei: bigint;
+    /** True when this digest appears in `postedTaskDigests` and reposting was allowed. */
+    readonly repost: boolean;
+}
+export interface PostingPlan {
+    readonly createdAt: string;
+    readonly creatorSafe: `0x${string}`;
+    readonly requester: string;
+    readonly terms: DefaultPostingTerms;
+    readonly approval: "explicit" | "auto";
+    readonly entries: readonly PostingPlanEntry[];
+    readonly totalEscrowValueWei: bigint;
+    readonly skipped: readonly PostingSkip[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: MIT
+export {};

package/package.json

@@ -1,13 +1,53 @@
 {
   "name": "@jinn-network/task-posting",
-  "version": "0.0.0",
-  "description": "Name reservation for npm trusted-publisher setup. Not a platform receipt.",
-  "license": "Apache-2.0",
+  "version": "0.1.0-canary.sha.786221faf848b3c859ddbc76fec09338df64d83b",
+  "description": "Supply policy for marketplace posting: which admitted, sealed task pairs post, when, at what terms, with the escrow surfaced before spending.",
+  "type": "module",
+  "packageManager": "yarn@4.13.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Jinn-Network/mono.git"
+    "url": "https://github.com/Jinn-Network/mono.git",
+    "directory": "packages/task-supply/posting"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
   },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "pack:smoke": "node scripts/pack-smoke.mjs",
+    "prepack": "yarn build"
+  },
+  "dependencies": {
+    "@jinn-network/marketplace-binding": "0.1.0-canary.sha.786221faf848b3c859ddbc76fec09338df64d83b",
+    "@jinn-network/task-execution-protocol": "0.1.0-canary.sha.786221faf848b3c859ddbc76fec09338df64d83b"
+  },
+  "devDependencies": {
+    "@jinn-network/task-derivation": "0.1.0-canary.sha.786221faf848b3c859ddbc76fec09338df64d83b",
+    "@jinn-network/task-execution-backend": "0.1.0-canary.sha.786221faf848b3c859ddbc76fec09338df64d83b",
+    "@jinn-network/task-execution-profiles": "0.1.0-canary.sha.786221faf848b3c859ddbc76fec09338df64d83b",
+    "@jinn-network/trust-core": "0.1.0-canary.sha.786221faf848b3c859ddbc76fec09338df64d83b",
+    "@jinn-network/trust-resolve": "0.1.0-canary.sha.786221faf848b3c859ddbc76fec09338df64d83b",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8"
+  },
+  "gitHead": "786221faf848b3c859ddbc76fec09338df64d83b"
 }