@kici-dev/compiler 0.6.1 → 0.7.0

package/dist/llm-context/llms-features.txt

@@ -66,7 +66,7 @@ You declare a gate in your workflow with `approval`. It is available at three le
 - **Job** — hold the job before any of its steps run.
 - **Workflow** — hold the whole run before any job is dispatched.
 
-A step-level gate can also fire **only when a check/apply step finds drift** — Terraform's plan→apply, per step. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-whendrift) below.
+A step-level gate can also fire **only when a check/apply step finds drift** — Terraform's plan→apply, per step. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-when-drift) below.
 
 Approvers are named as **teams** and **users**. A team is an operator-defined group of org members; your workflow code may name a team but can never change its membership, which is what makes a team clause a real gate rather than a suggestion. See [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/) for how operators define teams, the approval queue, and expiry; see [the architecture overview](https://docs.kici.dev/architecture/approvals/) for how a hold is evaluated and resumed.
 
@@ -137,7 +137,7 @@ approval: {
 
 | Field       | Type                  | Description                                                                                                                                                                                                      |
 | ----------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-whendrift).                                      |
+| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-when-drift).                                     |
 | `approvers` | `ApproverClause[]`    | The AND list of `{ team }` / `{ user }` clauses. An empty list means "any approval-capable member".                                                                                                              |
 | `reason`    | `string`              | A human-readable label shown in the dashboard queue and the held-for-approval status check.                                                                                                                      |
 | `timeout`   | `number`              | Per-gate expiry in **seconds**, overriding the org default. Must be a **positive integer** number of seconds; a non-positive or non-finite value is rejected at compile time. On expiry the element is rejected. |
@@ -316,7 +316,7 @@ Available rules:
 - **Branch restrictions** — only allow specific branches to deploy.
 - **Required reviewer approvals** — gate the run on human sign-off.
 - **Wait timers** — delay execution for a fixed period.
-- **Concurrency limits** — prevent collisions between parallel deployments.
+- **Concurrency limits** — cap how many jobs run against the context at once.
 
 <!-- /help:contexts-protection -->
 
@@ -405,7 +405,7 @@ job('deploy', {
 
 **Skip-on-test (allow-and-warn).** On a test or local run (`kici run remote`, `kici run <event> --local`), a bound context never rejects the run. Any bound context that disallows local execution (`allowLocalExecution: false`) — or that is not configured — is **skipped**: its variables and secrets are omitted from the merge and its gates are not evaluated. The run proceeds, and a user-visible warning naming the skipped context(s) is shown both on the `kici run remote` CLI output and on the dashboard run view. This makes the test-only-variables pattern work: with `contexts: ['staging', 'my-testing']` where only `my-testing` allows local execution, a test run resolves just `my-testing`'s variables and warns that `staging` was skipped. If every bound context is skipped, the job runs with no environment variables. This is intentionally different from a fixture `secrets:` mapping, which is fail-closed — see the [testing guide](https://docs.kici.dev/user/testing-guide/).
 
-**Unconfigured contexts contribute nothing at dispatch.** At dispatch time a bound context name with no matching configured context (and no matching glob context) simply adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic context resolving to an as-yet-unconfigured name does today.
+**Unconfigured contexts contribute nothing at dispatch.** At dispatch time a bound context name with no matching configured context (and no matching glob context) adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic context resolving to an as-yet-unconfigured name does today.
 
 **Registration rejects a provably-unsatisfiable binding.** When a workflow is registered, KiCI statically checks every multi-context binding: a bound context that does not exist, a disabled one, or two contexts with mutually-exclusive fixed branch / trigger-type / repository restrictions (no value can satisfy both) makes the binding provably unsatisfiable, and the registration is rejected with a precise message naming the job, the contexts, and the rule — for example `unsatisfiable context binding: job 'deploy' binds contexts [staging, my-testing] with mutually exclusive branch restrictions (no value satisfies all bound contexts)`. Bindings whose restrictions use globs are undecidable at registration and fall through to the dispatch-time gate check instead.
 
@@ -608,6 +608,36 @@ The children of a matrix job count individually against the limit. A three-child
 matrix bound to a context with a limit of two dispatches two children and applies
 the strategy above to the third.
 
+A job counts against the limit from the moment it is dispatched until it
+finishes. It does not have to reach an agent first.
+
+#### What the limit does and does not guarantee
+
+A context concurrency limit is a **throughput control**. Treat it as a cap on
+how much work runs at once, not as a lock.
+
+Two events that arrive in the same instant read the limit before either job is
+recorded, so each can be admitted. The window is short — the time between one
+read and one write — but it is real, and it grows with the number of
+orchestrator processes serving the context.
+
+When a job must never run beside another copy of itself — a production deploy,
+a database migration — declare a workflow-level
+[concurrency group](https://docs.kici.dev/user/concurrency/) as well:
+
+```typescript
+export default workflow('deploy', {
+  on: push({ branches: ['main'] }),
+  concurrency: { group: () => 'deploy-prod', max: 1 },
+  jobs: [/* ... */],
+});
+```
+
+That mechanism claims its slot inside a single database transaction, so two
+runs arriving together cannot both take it. The two are complementary: the
+context limit caps throughput across every workflow bound to the context, and
+the concurrency group serializes one workflow against itself.
+
 ## Dashboard management
 
 ### Creating contexts
@@ -914,7 +944,7 @@ registries: [
 ## Security model
 
 - **Per-context scoping.** Every `tokenSecret` and `installEnv` entry is qualified with a context name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named context **before** resolving any secret, so a workflow that wants a `production` token from a feature branch is rejected exactly like a job that tries to deploy to `production` from a feature branch. A reviewer-gated install context **pauses** the whole workflow dispatch as a workflow-scoped held run instead of resolving the token — see [Reviewer-gated installs](https://docs.kici.dev/user/private-registries/#reviewer-gated-installs) below.
-- **Untrusted refs get no tokens.** When the trust resolution returns anything other than `trusted` — every fork pull request does — the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep. A fork pull request cannot observe a registry token, even if a context lacks an explicit [minimum trust](https://docs.kici.dev/user/contexts/#minimum-trust) rule.
+- **Untrusted refs get no tokens.** When the trust resolution returns anything other than `trusted` — every fork pull request does — the orchestrator strips `npmRegistries`, `installEnvSecrets`, and a container job's [registry credentials](https://docs.kici.dev/user/container-jobs/#private-images) out of the dispatch. The install runs without auth and fails naturally on the first private dep, and a private base image fails to pull. A fork pull request cannot observe a registry token, even if a context lacks an explicit [minimum trust](https://docs.kici.dev/user/contexts/#minimum-trust) rule.
 - **Lifecycle scripts disabled.** Whenever a private registry is in scope, the agent runs the install with `--ignore-scripts` (npm, pnpm, and yarn classic alike; yarn berry gets the equivalent `enableScripts: false`). A malicious `preinstall` / `postinstall` hook in committed `package.json` cannot read the synthesized token env vars, even though they exist in the install subprocess. For a pnpm or yarn workspace, the agent builds your in-repo dependency closure as a separate step **after** the install's auth is torn down, so build scripts never see the tokens either.
 - **Stderr is redacted.** If the install fails, the agent masks every token literal out of the surfaced stderr / stdout chunks before logging.
 - **Job-scoped env-var names.** The synthesized auth env var is `KICI_NPM_TOKEN_<jobIdShort>_<i>` where `jobIdShort` is the first 8 chars of the dispatched job id. The name is unguessable from outside the install subprocess and not reused across jobs.
@@ -950,7 +980,7 @@ The dashboard JSON lives at `infra/terraform/modules/grafana/dashboards/install-
 ## See also
 
 - [Secrets](https://docs.kici.dev/user/secrets/) — how to seed the `<context>:<secret-name>` values referenced by `tokenSecret` / `installEnv`.
-- [Contexts](https://docs.kici.dev/user/contexts/) — protection rules (`branch_restrictions`, `requires_review`, `minimum_trust`) that the install gate inherits.
+- [Contexts](https://docs.kici.dev/user/contexts/) — protection rules (branch restrictions, required reviewers, minimum trust) that the install gate inherits.
 - [Operator: `kici-admin org-settings`](https://docs.kici.dev/operator/orchestrator/kici-admin/org-settings/#org-settings----org-level-security-policy) — the `allow_http_npm_registries` toggle and other org-scoped knobs.
 
 ---
@@ -1068,6 +1098,107 @@ and the step never holds signing credentials — the orchestrator mints and sign
 the token on the step's behalf from its own run records. Like `attestProvenance`,
 it is only available inside a running job step.
 
+## ID-token claims and cloud trust policies
+
+A cloud provider's OIDC trust policy decides which builds may assume a role. The
+token below is what your policy matches on, so read this section before you
+write one.
+
+### The claim set
+
+| Claim                         | Value                                                                                                            |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `iss`                         | Your orchestrator's provenance issuer                                                                            |
+| `aud`                         | The audience you asked for                                                                                       |
+| `sub`                         | The build identity — see the two shapes below                                                                    |
+| `repository`                  | `owner/repo` the run acted on                                                                                    |
+| `ref`                         | The branch or tag the run PRESENTS. For a pull request this is the **base** branch, not the contributor's branch |
+| `base_ref`                    | The same value as `ref`, named the way GitHub Actions names it                                                   |
+| `head_ref`                    | The pull request's HEAD branch; `''` for a non-PR run                                                            |
+| `head_repository`             | `owner/repo` of the pull-request HEAD — the contributor's fork for a fork PR; `''` for a non-PR run              |
+| `is_fork`                     | `'true'`, `'false'`, or `'unresolved'`                                                                           |
+| `event_name`                  | The event that started the run (`push`, `pull_request:opened`, `schedule`, …)                                    |
+| `trust_tier`                  | The resolved trust tier of the triggering actor, or `'unresolved'`                                               |
+| `actor`                       | Provider login of the triggering actor                                                                           |
+| `sha`                         | The run's commit                                                                                                 |
+| `workflow_ref`                | `<workflow name>@<sha>`                                                                                          |
+| `kici_run_id` / `kici_job_id` | The run and job this token was minted for                                                                        |
+| `org_id`                      | Your organization id                                                                                             |
+
+Every claim in the table is **always present**. A value the run did not resolve
+is `''` or `'unresolved'`, never omitted and never guessed. That matters: an
+absent claim makes a `StringEquals` condition pass, which would silently remove
+a constraint you wrote expecting it to be enforced.
+
+### The two `sub` shapes
+
+```
+push, tag, schedule, …     repo:<owner/repo>:ref:<ref>:workflow:<workflow name>
+pull request, review       repo:<owner/repo>:pull_request
+```
+
+The pull-request shape carries **no ref segment**, mirroring GitHub Actions. A
+pull request's `ref` is its base branch. So a ref-bearing subject would be
+identical for a fork pull request targeting `main` and a trusted push to `main`.
+A policy pinning that subject would hand your cloud role to any contributor who
+opened a pull request running the same workflow.
+
+**A re-run keeps the shape of the run it repeats.** Re-running a pull-request
+run presents `repo:<owner/repo>:pull_request`, because it rebuilds the same
+commit from the same source. Its `event_name` claim still reads `rerun` — that
+claim says what started the run, while `sub` says which identity the run
+presents. A policy that pins the branch-shaped subject therefore does not match
+a re-run of a pull request, which is the same protection the first run gets.
+
+### A worked AWS trust policy
+
+Pin `sub`, and pin the fork context too. `sub` alone tells you a pull request
+ran; it does not tell you whose code ran.
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/orch.example.com" },
+      "Action": "sts:AssumeRoleWithWebIdentity",
+      "Condition": {
+        "StringEquals": {
+          "orch.example.com:aud": "sts.amazonaws.com",
+          "orch.example.com:sub": "repo:acme/app:ref:main:workflow:deploy",
+          "orch.example.com:is_fork": "false",
+          "orch.example.com:head_repository": "acme/app",
+          "orch.example.com:trust_tier": "trusted"
+        }
+      }
+    }
+  ]
+}
+```
+
+This grants the role only to a run on `main` in `acme/app`, from code in that
+same repository, triggered by an actor your orchestrator resolved as trusted.
+A fork pull request fails on all three of the extra conditions, and a run whose
+context did not resolve fails too — `'unresolved'` matches none of them, so the
+policy fails closed.
+
+To let a same-repo pull request assume the role, add a second statement pinning
+`"sub": "repo:acme/app:pull_request"` alongside `"is_fork": "false"` and
+`"head_repository": "acme/app"`.
+
+### Migrating an existing policy
+
+If you already pin a ref-bearing `sub` for pull-request runs, that policy stops
+matching once you upgrade — which is the fix, because it was matching runs it
+should not have. Move it to `repo:<owner/repo>:pull_request` plus the fork
+conditions above. The same move covers a re-run of a pull request, which
+presents the pull-request subject too.
+
+While you migrate, `KICI_OIDC_LEGACY_PR_SUB=1` on the orchestrator restores the
+old subject. It restores the collision with it, so treat it as a short bridge,
+not a setting. See [deprecations](https://docs.kici.dev/user/deprecations/).
+
 ## Verifying an attestation
 
 Verify a bundle with the `kici verify-attestation` command. It establishes the