@kici-dev/engine 0.5.0 → 0.6.1

package/dist/trigger/decision-trace.js

@@ -6,15 +6,37 @@ import { describeTextMatch } from "./text-match.js";
 * Records every check performed during trigger evaluation.
 */
 /**
+* Max characters of any free-text field a trace entry carries, so an
+* essay-length input stays bounded.
+*
+* The entry count is capped separately, downstream, but a count bound alone
+* bounds nothing: a single `paths` entry names every changed file in the push
+* and a single `bodyMatch` entry quotes a comment body an outsider authored, so
+* fifty entries can still be megabytes. The forwarded trace rides one WebSocket
+* frame to the Platform, and a frame past the server's payload ceiling closes
+* the connection — stalling every delivery for that organization until it
+* reconnects. Bounding at the point each field is minted is what makes the
+* downstream size guards a backstop rather than the only limit.
+*/
+const TRACE_TEXT_MAX = 200;
+/** Clamp one free-text trace field, marking a clamped value with an ellipsis. */
+function truncateTraceText(text) {
+	return text.length > 200 ? `${text.slice(0, 200)}…` : text;
+}
+/**
 * Create a new trace entry.
+*
+* Every free-text field is clamped here rather than at each call site: the
+* fields are fed from event content of unbounded size, and one unclamped call
+* site is enough to reintroduce an unbounded frame.
 */
 function createTraceEntry(check, pattern, value, passed, reason) {
 	return {
 		check,
-		pattern,
-		value,
+		pattern: truncateTraceText(pattern),
+		value: truncateTraceText(value),
 		passed,
-		reason
+		reason: reason === void 0 ? void 0 : truncateTraceText(reason)
 	};
 }
 /**
@@ -35,7 +57,9 @@ const TraceCheck = {
 	/** Tier-2 `filter` predicate, run by an agent in the global eval round. */
 	GlobalFilter: "filter",
 	/** Tier-0 declarative `commitMessage` filter, read from the normalized event. */
-	CommitMessage: "commitMessage"
+	CommitMessage: "commitMessage",
+	/** Materialization of a matched workflow's jobs, on the way to dispatch. */
+	Dispatch: "dispatch"
 };
 /**
 * Verdict vocabulary shared by both gates.
@@ -74,6 +98,18 @@ function createGlobalFilterTraceEntry(args) {
 	return createTraceEntry(TraceCheck.GlobalFilter, "filter(context) === true", verdictFor(args.run, args.indeterminate === true), args.run, args.reason);
 }
 /**
+* Record that a matched workflow could not be materialized into jobs.
+*
+* A workflow whose triggers matched and whose build then threw is absent from
+* every other record: no run row is created and no job is queued. Omitting it
+* from the trace as well leaves its author unable to tell it apart from a
+* workflow that was never registered — the exact indistinguishability the trace
+* exists to remove.
+*/
+function createDispatchFailureTraceEntry(reason) {
+	return createTraceEntry(TraceCheck.Dispatch, "jobs materialize", TraceVerdict.Excluded, false, reason);
+}
+/**
 * Return a copy of `decision` with `entries` appended to its checks.
 *
 * A decision is treated as a value, never mutated in place: the same object is
@@ -94,8 +130,6 @@ function appendChecks(decision, entries) {
 		summary: failed ? failed.reason ?? `Excluded by the ${failed.check} check` : decision.summary
 	};
 }
-/** Max characters of the message recorded in a trace, so an essay-length body stays bounded. */
-const TRACE_TEXT_MAX = 200;
 /**
 * Record the Tier-0 `commitMessage` filter's verdict for one trigger.
 *
@@ -104,10 +138,84 @@ const TRACE_TEXT_MAX = 200;
 * would tell an author their filter said no when nothing ever read it.
 */
 function createCommitMessageTraceEntry(args) {
-	const shown = args.text === void 0 ? "(absent)" : args.text.length > TRACE_TEXT_MAX ? `${args.text.slice(0, TRACE_TEXT_MAX)}…` : args.text;
+	const shown = args.text === void 0 ? "(absent)" : args.text.length > 200 ? `${args.text.slice(0, 200)}…` : args.text;
 	return createTraceEntry(TraceCheck.CommitMessage, describeTextMatch(args.match), verdictFor(args.passed, args.indeterminate === true), args.passed, args.reason ?? `message: ${JSON.stringify(shown)}`);
 }
 /**
+* What a withheld trace field is replaced with when the reader does not hold
+* `event_log:read_payload`.
+*
+* Lives here rather than beside the Platform's redactor because three packages
+* read it: the Platform writes it, the dashboard renders it, and the E2E suite
+* asserts the permission boundary against it. A literal repeated at each site
+* would drift into a marker one of them no longer recognizes.
+*/
+const REDACTED_TRACE_FIELD = "[redacted — requires event_log:read_payload]";
+/**
+* Workflow name the truncation marker carries.
+*
+* A reserved sentinel rather than a real workflow: it is written by one package
+* and read back by two others, so a literal repeated at each site would drift
+* into a marker nobody recognizes.
+*/
+const TRACE_TRUNCATION_WORKFLOW_NAME = "(trace truncated)";
+/**
+* Build the marker that stands in for the decisions a size budget dropped.
+*
+* The trace is truncated rather than discarded: a reader who is told nothing
+* cannot tell "matching never ran" from "the trace was too large to keep", and
+* those two have opposite answers to "why did my workflow not fire".
+*/
+function createTraceTruncationMarker(omitted) {
+	return {
+		workflowName: TRACE_TRUNCATION_WORKFLOW_NAME,
+		matched: false,
+		traceTruncated: true,
+		decisionsOmitted: omitted,
+		checks: [],
+		checksCount: 0,
+		summary: (omitted === 1 ? "1 further workflow decision was dropped: " : `${omitted} further workflow decisions were dropped: `) + "the trace exceeded the size budget for this delivery."
+	};
+}
+/**
+* UTF-8 byte length of `text`.
+*
+* Byte length, never `String.length`: the latter counts UTF-16 code units, so a
+* CJK-heavy comment body measures at roughly a third of the bytes it actually
+* costs on the wire and in the stored row.
+*/
+function utf8ByteLength(text) {
+	return new TextEncoder().encode(text).length;
+}
+/**
+* Drop trailing decisions until the serialized array fits `maxBytes`, appending
+* a marker naming how many were dropped.
+*
+* Shared by the orchestrator, which bounds what it puts on the wire, and the
+* Platform, which bounds what it stores. Two independent budgets over one
+* shape: keeping one implementation is what stops them from disagreeing about
+* what a truncated trace looks like.
+*/
+function truncateDecisionsToByteBudget(decisions, maxBytes) {
+	if (utf8ByteLength(JSON.stringify(decisions)) <= maxBytes) return {
+		decisions: [...decisions],
+		omitted: 0
+	};
+	let used = 3 + utf8ByteLength(JSON.stringify(createTraceTruncationMarker(decisions.length)));
+	const kept = [];
+	for (const decision of decisions) {
+		const cost = utf8ByteLength(JSON.stringify(decision)) + 1;
+		if (used + cost > maxBytes) break;
+		used += cost;
+		kept.push(decision);
+	}
+	const omitted = decisions.length - kept.length;
+	return {
+		decisions: [...kept, createTraceTruncationMarker(omitted)],
+		omitted
+	};
+}
+/**
 * Create a workflow decision record.
 */
 function createWorkflowDecision(workflowName, matched, checks, matchedTrigger, summary) {
@@ -120,6 +228,6 @@ function createWorkflowDecision(workflowName, matched, checks, matchedTrigger, s
 	};
 }
 //#endregion
-export { TraceCheck, TraceVerdict, appendChecks, createCommitMessageTraceEntry, createContentRequirementsTraceEntry, createGlobalFilterTraceEntry, createTraceEntry, createWorkflowDecision };
+export { REDACTED_TRACE_FIELD, TRACE_TEXT_MAX, TRACE_TRUNCATION_WORKFLOW_NAME, TraceCheck, TraceVerdict, appendChecks, createCommitMessageTraceEntry, createContentRequirementsTraceEntry, createDispatchFailureTraceEntry, createGlobalFilterTraceEntry, createTraceEntry, createTraceTruncationMarker, createWorkflowDecision, truncateDecisionsToByteBudget, truncateTraceText, utf8ByteLength };
 
 //# sourceMappingURL=decision-trace.js.map

package/dist/trigger/matcher.js

@@ -542,12 +542,14 @@ function matchKiciEventTrigger(trigger, event, traces) {
 	traces.push(createTraceEntry("event name", trigger.eventName, eventName, nameMatches));
 	if (!nameMatches) return false;
 	if (trigger.match && Object.keys(trigger.match).length > 0) {
-		const matches = matchJsonPath(event.payload.payload ?? {}, trigger.match);
+		const eventPayload = event.payload.payload ?? {};
+		const matches = matchJsonPath(eventPayload, trigger.match);
 		traces.push(createTraceEntry("jsonpath match", JSON.stringify(trigger.match), "(payload)", matches));
 		if (!matches) return false;
 	}
 	if (trigger.not && Object.keys(trigger.not).length > 0) {
-		const passes = matchJsonPathNot(event.payload.payload ?? {}, trigger.not);
+		const eventPayload = event.payload.payload ?? {};
+		const passes = matchJsonPathNot(eventPayload, trigger.not);
 		traces.push(createTraceEntry("jsonpath not", JSON.stringify(trigger.not), "(payload)", passes));
 		if (!passes) return false;
 	}

package/dist/trigger/types.d.ts

@@ -33,6 +33,11 @@
  * Schema version 34 (additive): adds LockWorkflow.hasFilter (workflow-level pre-dispatch filter predicate).
  * Schema version 35 (additive): adds `commitMessage` (LockTextMatch) to the push/pr/tag
  *   git-event triggers, and contains/notContains/notMatches to LockContentRequirement.
+ * Schema version 36 (additive): adds LockJob.invoke (invokeSource gate, incl. optional).
+ * Schema version 37 (additive): adds LockJob.gitCredentials (named git credential refs).
+ * Schema version 38 (additive): adds container.auth (private-registry credentials for the job image).
+ * Schema version 39 (additive): adds container.dockerfile/context/target/args (build the
+ *   job's image from a Dockerfile in the repo) and container.auth.registry.
  */
 import { z } from 'zod';
 import type { ProviderType } from '../provider/types.js';
@@ -45,7 +50,7 @@ import { ExecutionJobStatus } from '../protocol/messages/execution-status.js';
  * schema change (additive or breaking); the bump-history comment above records
  * which. See `BREAKING_FLOOR` for the compatibility-window semantics.
  */
-export declare const SCHEMA_VERSION: 35;
+export declare const SCHEMA_VERSION: 39;
 /**
  * Oldest lock schema version this codebase can still read correctly — the lower
  * bound of the acceptance window.
@@ -736,9 +741,34 @@ export interface ResolvedSandboxGrant {
     /** Run the container as this user (operator-config path only in Phase 2). */
     user?: string;
 }
+/**
+ * Invoke-gate action carried on a lock job (compiled from `invokeSource()`).
+ * A job carrying this never runs steps on an agent: the orchestrator emits the
+ * named kici event at the source repo and gates on the runs it triggers.
+ */
+export interface LockInvoke {
+    /** The kici event name to emit; source-repo workflows subscribe with `kiciEvent({ name })`. */
+    readonly event: string;
+    /** Target scope. `'source'` targets exactly the source repo (the only v1 scope). */
+    readonly scope: 'source';
+    /** Optional event payload delivered to subscribers. */
+    readonly payload?: Readonly<Record<string, unknown>>;
+    /**
+     * When true, a zero-subscriber emit succeeds immediately (the repo may opt
+     * out). Absent/false (the default) fails the gate on zero subscribers.
+     */
+    readonly optional?: boolean;
+}
 export interface LockJob {
     readonly _type: 'static';
     readonly name: string;
+    /**
+     * Invoke-gate action. When set, the job is a gate: it never dispatches steps
+     * to an agent; the orchestrator emits `invoke.event` at the source repo and
+     * tracks each triggered run as a proxy child. Additive — an older
+     * orchestrator that does not understand it ignores it (the gate stays inert).
+     */
+    readonly invoke?: LockInvoke;
     /** Single-agent targeting matchers. Absent when the job uses `runsOnAll` instead. */
     readonly runsOn?: readonly LabelMatcher[];
     readonly excludeLabels?: readonly LabelMatcher[];
@@ -748,6 +778,16 @@ export interface LockJob {
      * `any` picks any available agent. Absent on a `runsOnAll` fan-out job.
      */
     readonly runsOnPick?: RunsOnPick;
+    /**
+     * Named git credentials for this job, as SECRET NAMES in qualified
+     * `<context>:<secret-name>` form — never credential material.
+     *
+     * `default` is used when a call names no credential; any other key is
+     * referenced by name. Additive: an older orchestrator that does not
+     * understand it simply passes it through in `jobConfig`, and an older agent
+     * ignores it (git falls back to its own mechanisms, exactly as before).
+     */
+    readonly gitCredentials?: Readonly<Record<string, Readonly<Record<string, string>>>>;
     /**
      * Host fan-out predicate (mutually exclusive with `runsOn`). When set, the job
      * fans out to every roster host matching the predicate, one pinned child per host.
@@ -814,15 +854,55 @@ export interface LockJob {
     readonly resources?: import('../scaler/resource-types.js').ResourceRequest;
     /**
      * Container image selecting the container execution backend on the agent. A
-     * bare image string or an object with `image` + optional `env`. When set, the
-     * agent's `determineExecutionMode` routes the job to the container sandbox
-     * (top priority), so the orchestrator threads it through dispatch as
-     * `jobConfig.container`. (Shape mirrors the SDK `string | ContainerConfig`;
-     * the engine cannot import the SDK, so it is inlined here.)
+     * bare image string, or an object naming exactly one image source: a
+     * finalized `image`, or a `dockerfile` the agent builds from the cloned tree
+     * before the job starts. When set, the agent's `determineExecutionMode`
+     * routes the job to the container sandbox (top priority), so the orchestrator
+     * threads it through dispatch as `jobConfig.container`. (Shape mirrors the SDK
+     * `string | ContainerConfig`, including `ContainerRegistryAuth`; the engine
+     * cannot import the SDK, so it is inlined here.)
      */
     readonly container?: string | {
-        readonly image: string;
+        /** Finalized image to pull. Exactly one of `image` / `dockerfile` is set. */
+        readonly image?: string;
+        /**
+         * Repo-relative Dockerfile the agent builds before the job runs.
+         *
+         * The agent re-validates this path against the resolved workdir: a lock
+         * file is repo content, so a path that escapes the tree must be refused
+         * on the agent too, not only by the SDK that wrote it.
+         */
+        readonly dockerfile?: string;
+        /** Repo-relative build context. Defaults to the repository root. */
+        readonly context?: string;
+        /** Build stage to stop at. */
+        readonly target?: string;
+        /**
+         * Build arguments. Plain strings — never secret references, because a
+         * build argument is recorded in the built image's history.
+         */
+        readonly args?: Record<string, string>;
         readonly env?: Record<string, string>;
+        /**
+         * Private-registry credentials for pulling `image`.
+         *
+         * Flattened `Sourced<Name>` pairs: exactly one half of each pair is
+         * set — `*Secret` names a `<context>:<secret-name>` entry to resolve,
+         * `*Value` carries material supplied at run time.
+         */
+        readonly auth?: {
+            readonly username?: string;
+            readonly usernameSecret?: string;
+            readonly usernameValue?: string;
+            readonly tokenSecret?: string;
+            readonly tokenValue?: string;
+            /**
+             * Registry host the credentials belong to. Derived from `image` when
+             * one is set; REQUIRED with `dockerfile`, whose base image is named
+             * inside the Dockerfile and cannot be read back out reliably.
+             */
+            readonly registry?: string;
+        };
     };
     /**
      * Workflow-declared per-job sandbox escape-hatch request (container jobs

package/dist/trigger/types.js

@@ -38,13 +38,18 @@ import { z } from "zod";
 * Schema version 34 (additive): adds LockWorkflow.hasFilter (workflow-level pre-dispatch filter predicate).
 * Schema version 35 (additive): adds `commitMessage` (LockTextMatch) to the push/pr/tag
 *   git-event triggers, and contains/notContains/notMatches to LockContentRequirement.
+* Schema version 36 (additive): adds LockJob.invoke (invokeSource gate, incl. optional).
+* Schema version 37 (additive): adds LockJob.gitCredentials (named git credential refs).
+* Schema version 38 (additive): adds container.auth (private-registry credentials for the job image).
+* Schema version 39 (additive): adds container.dockerfile/context/target/args (build the
+*   job's image from a Dockerfile in the repo) and container.auth.registry.
 */
 /**
 * Schema version the compiler emits into every lock file. Incremented on ANY
 * schema change (additive or breaking); the bump-history comment above records
 * which. See `BREAKING_FLOOR` for the compatibility-window semantics.
 */
-const SCHEMA_VERSION = 35;
+const SCHEMA_VERSION = 39;
 /**
 * Oldest lock schema version this codebase can still read correctly — the lower
 * bound of the acceptance window.

package/dist/ws/rate-limiter.js

@@ -79,10 +79,10 @@ var WsRateLimiter = class {
 	bytesCapacity;
 	disconnectAfterMs;
 	constructor(config) {
-		const bytesCapacity = config?.bytesCapacity ?? 2 * 1024 * 1024;
+		const bytesCapacity = config?.bytesCapacity ?? 2097152;
 		this.messages = new TokenBucket(config?.messageCapacity ?? 200, config?.messageRefillRate ?? 100);
-		this.bytes = new TokenBucket(bytesCapacity, config?.bytesRefillRate ?? 500 * 1024);
-		this.maxMessageSize = config?.maxMessageSize ?? 4 * 1024 * 1024;
+		this.bytes = new TokenBucket(bytesCapacity, config?.bytesRefillRate ?? 512e3);
+		this.maxMessageSize = config?.maxMessageSize ?? 4194304;
 		this.bytesCapacity = bytesCapacity;
 		this.disconnectAfterMs = config?.disconnectAfterMs ?? 5e3;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/engine",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Shared business logic for the KiCI CI/CD stack: protocol, triggers, state machine, and provider interfaces used by the Platform relay, orchestrator, and compiler.",
   "keywords": [
     "ci",
@@ -53,6 +53,10 @@
       "import": "./dist/webhook/signature.js",
       "types": "./dist/webhook/signature.d.ts"
     },
+    "./scaler/registry-auth": {
+      "import": "./dist/scaler/registry-auth.js",
+      "types": "./dist/scaler/registry-auth.d.ts"
+    },
     "./safe-regex": {
       "import": "./dist/safe-regex.js",
       "types": "./dist/safe-regex.d.ts"
@@ -105,6 +109,10 @@
       "import": "./dist/protocol/messages/oidc-mint.js",
       "types": "./dist/protocol/messages/oidc-mint.d.ts"
     },
+    "./protocol/messages/git-credential-relay": {
+      "import": "./dist/protocol/messages/git-credential-relay.js",
+      "types": "./dist/protocol/messages/git-credential-relay.d.ts"
+    },
     "./provenance/schema": {
       "import": "./dist/provenance/schema.js",
       "types": "./dist/provenance/schema.d.ts"
@@ -139,9 +147,9 @@
     }
   },
   "dependencies": {
-    "jose": "^6.1.0",
+    "jose": "^6.2.10",
     "jsonpath-plus": "^10.4.0",
-    "picomatch": "^4.0.5",
+    "picomatch": "^4.0.7",
     "safe-regex": "^2.1.1",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/engine@0.5.0",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fengine/0.5.0/4dbbd65e-049d-4dc9-8c49-6e9d7ed4bc9e",
+  "name": "@kici-dev/engine@0.6.1",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fengine/0.6.1/3af2cc4e-0d26-40f2-8700-367133e0f64c",
   "creationInfo": {
-    "created": "2026-08-15T19:15:34Z",
+    "created": "2026-09-02T03:01:17Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -54,7 +54,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.5.0",
+      "versionInfo": "0.6.1",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -65,17 +65,17 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.5.0"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.6.1"
         }
       ],
       "description": "Shared business logic for the KiCI CI/CD stack: protocol, triggers, state machine, and provider interfaces used by the Platform relay, orchestrator, and compiler.",
       "homepage": "https://kici.dev"
     },
     {
-      "SPDXID": "SPDXRef-Package-jose-6.2.3",
+      "SPDXID": "SPDXRef-Package-jose-6.2.10",
       "name": "jose",
-      "versionInfo": "6.2.3",
-      "downloadLocation": "https://registry.npmjs.org/jose/-/jose-6.2.3.tgz",
+      "versionInfo": "6.2.10",
+      "downloadLocation": "https://registry.npmjs.org/jose/-/jose-6.2.10.tgz",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
       "licenseDeclared": "MIT",
@@ -85,7 +85,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/jose@6.2.3"
+          "referenceLocator": "pkg:npm/jose@6.2.10"
         }
       ],
       "description": "JWA, JWS, JWE, JWT, JWK, JWKS for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes",
@@ -132,10 +132,10 @@
       "homepage": "https://github.com/s3u/JSONPath"
     },
     {
-      "SPDXID": "SPDXRef-Package-picomatch-4.0.5",
+      "SPDXID": "SPDXRef-Package-picomatch-4.0.7",
       "name": "picomatch",
-      "versionInfo": "4.0.5",
-      "downloadLocation": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.5.tgz",
+      "versionInfo": "4.0.7",
+      "downloadLocation": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.7.tgz",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
       "licenseDeclared": "MIT",
@@ -145,7 +145,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/picomatch@4.0.5"
+          "referenceLocator": "pkg:npm/picomatch@4.0.7"
         }
       ],
       "description": "Blazing fast and accurate glob matcher written in JavaScript, with no dependencies and full support for standard and extended Bash glob features, including braces, extglobs, POSIX brackets, and regular expressions.",
@@ -250,7 +250,7 @@
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package-jose-6.2.3",
+      "relatedSpdxElement": "SPDXRef-Package-jose-6.2.10",
       "relationshipType": "DEPENDS_ON"
     },
     {
@@ -260,7 +260,7 @@
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package-picomatch-4.0.5",
+      "relatedSpdxElement": "SPDXRef-Package-picomatch-4.0.7",
       "relationshipType": "DEPENDS_ON"
     },
     {