@kici-dev/engine 0.4.0 → 0.5.0

package/dist/trigger/types.d.ts

@@ -29,6 +29,10 @@
  * Schema version 30 (BREAKING): renames job-level `environments` to `contexts`.
  * Schema version 31 (additive): adds the workflows_failed_batch lock trigger.
  * Schema version 32 (additive): adds LockJob.sandbox (per-job escape-hatch request).
+ * Schema version 33 (additive): adds `requires` (declarative static content filter) to the push/pr/tag git-event triggers.
+ * 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.
  */
 import { z } from 'zod';
 import type { ProviderType } from '../provider/types.js';
@@ -41,7 +45,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: 32;
+export declare const SCHEMA_VERSION: 35;
 /**
  * Oldest lock schema version this codebase can still read correctly — the lower
  * bound of the acceptance window.
@@ -54,8 +58,8 @@ export declare const SCHEMA_VERSION: 32;
  * Bump rule: move this to the current `SCHEMA_VERSION` ONLY in the commit that
  * lands a `BREAKING` schema change (see the bump-history convention above). It
  * currently sits at 30 because v30 (`environments`→`contexts`) was the most
- * recent breaking bump; v31 and v32 were additive, so a v30 lock still reads
- * correctly.
+ * recent breaking bump; v31 through v35 were additive, so a v30 lock still
+ * reads correctly.
  */
 export declare const BREAKING_FLOOR: 30;
 /**
@@ -92,6 +96,121 @@ export interface LockBranchPattern {
     readonly pattern: string;
     readonly flags?: string;
 }
+/**
+ * A declarative query over one piece of text: literal substrings and/or a
+ * regex, in either direction. Pure DATA the orchestrator interprets — never
+ * author code — so it is safe to evaluate inside the orchestrator under the
+ * execution-purity model.
+ *
+ * Every entry in a list is a CONJUNCT: `contains: [a, b]` means the text
+ * contains `a` AND contains `b`. OR is expressed by declaring two triggers,
+ * since a workflow's trigger list is already "first match wins".
+ *
+ * This is the SDK-facing shape a workflow author writes; the compiler
+ * normalizes it to {@link LockTextMatch}.
+ */
+export interface TextMatch {
+    /** Literal substring(s). Every entry must be present. */
+    readonly contains?: string | readonly string[];
+    /** Literal substring(s). No entry may be present. */
+    readonly notContains?: string | readonly string[];
+    /** Regex(es), as a RegExp or a `/pattern/flags` string. Every one must match. */
+    readonly matches?: string | RegExp | readonly (string | RegExp)[];
+    /** Regex(es). None may match. */
+    readonly notMatches?: string | RegExp | readonly (string | RegExp)[];
+    /**
+     * Case-insensitive comparison for `contains`/`notContains` ONLY. Default false.
+     * It deliberately does not touch the regex keys: a regex already carries its
+     * own flags, and injecting `i` into a pattern whose author omitted it would
+     * silently change its meaning.
+     */
+    readonly ignoreCase?: boolean;
+}
+/**
+ * Lock-file form of {@link TextMatch}. The compiler normalizes every key to a
+ * flat array, and every regex to a `/pattern/flags` string, so the orchestrator
+ * matcher has exactly one shape to interpret.
+ */
+export interface LockTextMatch {
+    readonly contains?: readonly string[];
+    readonly notContains?: readonly string[];
+    /** Always in `/pattern/flags` form. */
+    readonly matches?: readonly string[];
+    /** Always in `/pattern/flags` form. */
+    readonly notMatches?: readonly string[];
+    readonly ignoreCase?: boolean;
+}
+/**
+ * How a file's bytes are parsed before a content query runs.
+ * `auto` picks by extension: `.json` → json, `.yaml`/`.yml` → yaml, else text.
+ */
+export type ContentFormat = 'json' | 'yaml' | 'text' | 'auto';
+/**
+ * Declarative static content filter: a query over the bytes of one source file
+ * at the event's ref. Pure DATA the orchestrator's own matcher interprets — never
+ * author code — so it is safe to evaluate in the orchestrator (Part B of the
+ * execution-purity model). Query keys
+ * (`exists`/`match`/`not`/`contains`/`notContains`/`matches`/`notMatches`) are
+ * AND-ed within an entry; `absent` is mutually exclusive with them and passes
+ * only when the file is missing.
+ *
+ * This is the SDK-facing shape a workflow author writes, which accepts a scalar
+ * or `RegExp` where the lock form ({@link LockContentRequirement}) carries a flat
+ * array of `/pattern/flags` strings — the compiler normalizes one to the other.
+ */
+export interface ContentRequirement {
+    /** Repo-relative path of the file to query. */
+    readonly file: string;
+    /** Parse format; defaults to `auto` when unset. */
+    readonly format?: ContentFormat;
+    /** JSONPath expressions that must each resolve to ≥1 node (json/yaml only). */
+    readonly exists?: readonly string[];
+    /** JSONPath → expected-value map; every expression must match (json/yaml only). */
+    readonly match?: Record<string, unknown>;
+    /** JSONPath → value map; passes only when NONE match (json/yaml only). */
+    readonly not?: Record<string, unknown>;
+    /** Literal substring(s) that must ALL be present in the raw file text. */
+    readonly contains?: string | readonly string[];
+    /** Literal substring(s) of which NONE may be present in the raw file text. */
+    readonly notContains?: string | readonly string[];
+    /** Regex(es) that must ALL match the raw file text (RegExp or `/pattern/flags`). */
+    readonly matches?: string | RegExp | readonly (string | RegExp)[];
+    /** Regex(es) of which NONE may match the raw file text. */
+    readonly notMatches?: string | RegExp | readonly (string | RegExp)[];
+    /** Case-insensitive `contains`/`notContains`. Default false. */
+    readonly ignoreCase?: boolean;
+    /** When true, the entry passes only if the file is absent. Excludes all query keys. */
+    readonly absent?: boolean;
+}
+/**
+ * Lock-file form of {@link ContentRequirement}. The compiler normalizes each
+ * raw-text key to the flat {@link LockTextMatch} shape, so the orchestrator
+ * matcher has one shape to interpret.
+ */
+export interface LockContentRequirement {
+    readonly file: string;
+    readonly format?: ContentFormat;
+    readonly exists?: readonly string[];
+    readonly match?: Record<string, unknown>;
+    readonly not?: Record<string, unknown>;
+    readonly contains?: readonly string[];
+    readonly notContains?: readonly string[];
+    readonly matches?: readonly string[];
+    readonly notMatches?: readonly string[];
+    readonly ignoreCase?: boolean;
+    readonly absent?: boolean;
+}
+/**
+ * Resolve a content requirement's parse format to a concrete value. An explicit
+ * non-`auto` format is returned as-is; `auto` (or unset) is resolved by the file
+ * extension: `.json` → json, `.yaml`/`.yml` → yaml, everything else text.
+ *
+ * Yaml-free (pure string logic) so it lives in the browser-safe barrel and is
+ * the single source of truth for both the compiler's compile-time serializer and
+ * the orchestrator's eval-time matcher — the two can never disagree about how a
+ * file's format is picked.
+ */
+export declare function resolveContentFormat(file: string, format: ContentFormat | undefined): 'json' | 'yaml' | 'text';
 /**
  * PR trigger in lock file.
  * Optimized for orchestrator event matching - flat structure with all filters accessible.
@@ -103,6 +222,10 @@ export interface LockPrTrigger {
     readonly sourceBranches: readonly LockBranchPattern[];
     readonly paths: readonly string[];
     readonly repos?: readonly LockBranchPattern[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly LockContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: LockTextMatch;
 }
 /**
  * Push trigger in lock file.
@@ -113,6 +236,10 @@ export interface LockPushTrigger {
     readonly branches: readonly LockBranchPattern[];
     readonly paths: readonly string[];
     readonly repos?: readonly LockBranchPattern[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly LockContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: LockTextMatch;
 }
 /**
  * Tag trigger in lock file.
@@ -122,6 +249,10 @@ export interface LockTagTrigger {
     readonly _type: 'tag';
     readonly patterns: readonly LockBranchPattern[];
     readonly repos?: readonly LockBranchPattern[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly LockContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: LockTextMatch;
 }
 /**
  * Comment trigger in lock file.
@@ -426,17 +557,27 @@ export type LockStepEntry = LockStep | LockParallelStep;
 /** Type guard distinguishing a parallel group from an ordinary lock step. */
 export declare function isLockParallelStep(entry: LockStepEntry): entry is LockParallelStep;
 /**
- * Inline expression value for pure dynamic functions.
- * The compiler serializes pure functions as { _type: 'inline', expression: '(event) => ...' }
- * and the orchestrator evaluates them via vm.runInNewContext at dispatch time.
- * struct with discriminant and expression field.
- * _type: 'inline' alongside existing 'static' and 'dynamic' discriminants.
+ * Serialized inline expression for a dynamic env/context/concurrencyGroup
+ * field, shaped as `{ _type: 'inline', expression: '(event) => ...' }`
+ * alongside the existing 'static' and 'dynamic' discriminants.
+ *
+ * @deprecated Schema v11 inline expressions are no longer evaluated in the
+ * orchestrator. Dynamic env/context/concurrencyGroup fields are resolved on the
+ * eval agent's init-runner. The compiler no longer emits this type; readers keep
+ * recognizing it only to defer an old lock's field to the init round. Removed at
+ * the next major (v1.0.0).
  */
 export interface LockInlineValue {
     readonly _type: 'inline';
     readonly expression: string;
 }
-/** Type guard for inline expression values */
+/**
+ * Type guard for inline expression values.
+ *
+ * @deprecated See {@link LockInlineValue}. Retained only so a reader can
+ * recognize an old lock's inline field and defer it to the eval agent's
+ * init-runner. Removed at the next major (v1.0.0).
+ */
 export declare function isLockInlineValue(value: unknown): value is LockInlineValue;
 /**
  * Author-facing keyword sugar for a `needs` edge's run condition. Each keyword
@@ -640,21 +781,28 @@ export interface LockJob {
     readonly rules?: readonly LockRule[];
     readonly description?: string;
     /**
-     * Bound contexts in merge order. Each entry is a static name or inline
-     * expression (pure function); `dynamic` is set when it is a function resolved at
-     * two-phase eval. Later entries override earlier ones on name collisions.
+     * Bound contexts in merge order. Each entry is a static name; `dynamic` is set
+     * when it is a function resolved on the eval agent's init-runner. Later entries
+     * override earlier ones on name collisions. The `LockInlineValue` shape is a
+     * deprecated form still accepted from old locks (see {@link LockInlineValue}).
      */
     readonly contexts?: ReadonlyArray<{
         value: string | LockInlineValue;
         dynamic: boolean;
     }>;
-    /** Static environment variables or inline expression (pure function). */
+    /**
+     * Static environment variables. A deprecated `LockInlineValue` shape is still
+     * accepted from old locks (see {@link LockInlineValue}).
+     */
     readonly env?: Record<string, string> | LockInlineValue;
-    /** When true, env is dynamic (function) -- resolved at orchestrator two-phase eval or inline. */
+    /** When true, env is dynamic (function) -- resolved on the eval agent's init-runner. */
     readonly dynamicEnv?: boolean;
-    /** Concurrency group name (static string) or inline expression (pure function). */
+    /**
+     * Concurrency group name (static string). A deprecated `LockInlineValue` shape
+     * is still accepted from old locks (see {@link LockInlineValue}).
+     */
     readonly concurrencyGroup?: string | LockInlineValue;
-    /** When true, concurrencyGroup is dynamic (function) -- resolved at orchestrator two-phase eval or inline. */
+    /** When true, concurrencyGroup is dynamic (function) -- resolved on the eval agent's init-runner. */
     readonly dynamicConcurrencyGroup?: boolean;
     /** Total job wall-clock timeout in milliseconds (init + all steps + hooks). Threaded to the agent via jobConfig. */
     readonly timeout?: number;
@@ -769,6 +917,13 @@ export interface LockWorkflow {
     readonly timeout?: number;
     /** Normalized approval gate; when set the whole run is held before any job dispatches. */
     readonly approval?: LockApproval;
+    /**
+     * True when the workflow declares a `filter` predicate. A bare flag, not a
+     * source reference: `LockWorkflow.source` already identifies the module and
+     * export, so the eval agent loads it and reads `.filter` off the workflow
+     * object. Mirrors the `dynamicEnv` / `dynamicConcurrencyGroup` convention.
+     */
+    readonly hasFilter?: boolean;
 }
 /**
  * Complete lock file structure.
@@ -783,7 +938,7 @@ export interface LockWorkflow {
  * v8 adds runsOn polymorphic type (string | string[] | selector) and excludeLabels.
  * v9 adds repos/notRepos repo pattern fields to git-event triggers for global workflow matching.
  * v10 removes notRepos/notPaths fields; negative patterns use ! prefix in repos/paths arrays.
- * v11 adds LockInlineValue type for pure function inline evaluation.
+ * v11 adds the LockInlineValue type (deprecated; inline dynamic fields are resolved on the eval agent).
  * v12 adds workflow-level registries and installEnv for private npm registry auth.
  * v13 adds job-level and workflow-level timeout.
  */
@@ -869,6 +1024,13 @@ export interface SimulatedEvent {
      * to the previous owner.
      */
     senderUserId?: string;
+    /**
+     * Text a `commitMessage` trigger filter is tested against: the full head-commit
+     * message for push/tag, or PR title + body for pull-request events. Absent when
+     * the provider payload carries none — which a `commitMessage` filter treats as
+     * INDETERMINATE (fail-visible), never as an empty string.
+     */
+    commitMessage?: string;
     /** Repository identifier where the event occurred (e.g., "owner/repo").
      *  Used by global workflow repo pattern matching. */
     sourceRepo?: string;

package/dist/trigger/types.js

@@ -34,13 +34,17 @@ import { z } from "zod";
 * Schema version 30 (BREAKING): renames job-level `environments` to `contexts`.
 * Schema version 31 (additive): adds the workflows_failed_batch lock trigger.
 * Schema version 32 (additive): adds LockJob.sandbox (per-job escape-hatch request).
+* Schema version 33 (additive): adds `requires` (declarative static content filter) to the push/pr/tag git-event triggers.
+* 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 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 = 32;
+const SCHEMA_VERSION = 35;
 /**
 * Oldest lock schema version this codebase can still read correctly — the lower
 * bound of the acceptance window.
@@ -53,15 +57,38 @@ const SCHEMA_VERSION = 32;
 * Bump rule: move this to the current `SCHEMA_VERSION` ONLY in the commit that
 * lands a `BREAKING` schema change (see the bump-history convention above). It
 * currently sits at 30 because v30 (`environments`→`contexts`) was the most
-* recent breaking bump; v31 and v32 were additive, so a v30 lock still reads
-* correctly.
+* recent breaking bump; v31 through v35 were additive, so a v30 lock still
+* reads correctly.
 */
 const BREAKING_FLOOR = 30;
+/**
+* Resolve a content requirement's parse format to a concrete value. An explicit
+* non-`auto` format is returned as-is; `auto` (or unset) is resolved by the file
+* extension: `.json` → json, `.yaml`/`.yml` → yaml, everything else text.
+*
+* Yaml-free (pure string logic) so it lives in the browser-safe barrel and is
+* the single source of truth for both the compiler's compile-time serializer and
+* the orchestrator's eval-time matcher — the two can never disagree about how a
+* file's format is picked.
+*/
+function resolveContentFormat(file, format) {
+	if (format && format !== "auto") return format;
+	const lower = file.toLowerCase();
+	if (lower.endsWith(".json")) return "json";
+	if (lower.endsWith(".yaml") || lower.endsWith(".yml")) return "yaml";
+	return "text";
+}
 /** Type guard distinguishing a parallel group from an ordinary lock step. */
 function isLockParallelStep(entry) {
 	return entry.kind === "parallel";
 }
-/** Type guard for inline expression values */
+/**
+* Type guard for inline expression values.
+*
+* @deprecated See {@link LockInlineValue}. Retained only so a reader can
+* recognize an old lock's inline field and defer it to the eval agent's
+* init-runner. Removed at the next major (v1.0.0).
+*/
 function isLockInlineValue(value) {
 	return typeof value === "object" && value !== null && value._type === "inline";
 }
@@ -178,6 +205,6 @@ const changedFilesStatusSchema = z.enum([
 	"skipped"
 ]);
 //#endregion
-export { BREAKING_FLOOR, NeedsEntrySchema, NeedsGroupEntrySchema, NeedsRunOn, NeedsWhen, OnUnreachableMode, RunsOnPick, SANDBOX_NETWORK_MODES, SCHEMA_VERSION, changedFilesStatusSchema, isLockDynamicJobFn, isLockInlineValue, isLockParallelStep, isLockStaticJob, resolveWhenToRunOn };
+export { BREAKING_FLOOR, NeedsEntrySchema, NeedsGroupEntrySchema, NeedsRunOn, NeedsWhen, OnUnreachableMode, RunsOnPick, SANDBOX_NETWORK_MODES, SCHEMA_VERSION, changedFilesStatusSchema, isLockDynamicJobFn, isLockInlineValue, isLockParallelStep, isLockStaticJob, resolveContentFormat, resolveWhenToRunOn };
 
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/engine",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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",
@@ -45,10 +45,18 @@
       "import": "./dist/trigger/trigger-event-type.js",
       "types": "./dist/trigger/trigger-event-type.d.ts"
     },
+    "./trigger/content-requirements": {
+      "import": "./dist/trigger/content-requirements.js",
+      "types": "./dist/trigger/content-requirements.d.ts"
+    },
     "./webhook/signature": {
       "import": "./dist/webhook/signature.js",
       "types": "./dist/webhook/signature.d.ts"
     },
+    "./safe-regex": {
+      "import": "./dist/safe-regex.js",
+      "types": "./dist/safe-regex.d.ts"
+    },
     "./labels/compile": {
       "import": "./dist/labels/compile.js",
       "types": "./dist/labels/compile.d.ts"
@@ -135,6 +143,7 @@
     "jsonpath-plus": "^10.4.0",
     "picomatch": "^4.0.5",
     "safe-regex": "^2.1.1",
+    "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/engine@0.4.0",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fengine/0.4.0/9e27a29f-2dd8-4cc5-9c0f-4e6591fd02e7",
+  "name": "@kici-dev/engine@0.5.0",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fengine/0.5.0/4dbbd65e-049d-4dc9-8c49-6e9d7ed4bc9e",
   "creationInfo": {
-    "created": "2026-08-09T16:02:43Z",
+    "created": "2026-08-15T19:15:34Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -54,7 +54,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.4.0",
+      "versionInfo": "0.5.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -65,7 +65,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.4.0"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.5.0"
         }
       ],
       "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.",
@@ -191,6 +191,26 @@
       "description": "detect possibly catastrophic, exponential-time regular expressions",
       "homepage": "https://github.com/davisjam/safe-regex"
     },
+    {
+      "SPDXID": "SPDXRef-Package-yaml-2.9.0",
+      "name": "yaml",
+      "versionInfo": "2.9.0",
+      "downloadLocation": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+      "filesAnalyzed": false,
+      "licenseConcluded": "NOASSERTION",
+      "licenseDeclared": "ISC",
+      "copyrightText": "NOASSERTION",
+      "supplier": "NOASSERTION",
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:npm/yaml@2.9.0"
+        }
+      ],
+      "description": "JavaScript parser and stringifier for YAML",
+      "homepage": "https://eemeli.org/yaml/"
+    },
     {
       "SPDXID": "SPDXRef-Package-zod-4.4.3",
       "name": "zod",
@@ -248,6 +268,11 @@
       "relatedSpdxElement": "SPDXRef-Package-safe-regex-2.1.1",
       "relationshipType": "DEPENDS_ON"
     },
+    {
+      "spdxElementId": "SPDXRef-RootPackage",
+      "relatedSpdxElement": "SPDXRef-Package-yaml-2.9.0",
+      "relationshipType": "DEPENDS_ON"
+    },
     {
       "spdxElementId": "SPDXRef-RootPackage",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",