owenloop 0.4.1 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +71 -0
- package/README.md +182 -53
- package/bin/owenloop.mjs +50 -2
- package/dist/packages/work/src/agent/brief.d.ts +176 -0
- package/dist/packages/work/src/agent/brief.js +197 -0
- package/dist/packages/work/src/agent/loop.d.ts +141 -0
- package/dist/packages/work/src/agent/loop.js +669 -0
- package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
- package/dist/packages/work/src/agent/model-policy.js +138 -0
- package/dist/packages/work/src/agent/workdir.d.ts +210 -0
- package/dist/packages/work/src/agent/workdir.js +319 -0
- package/dist/packages/work/src/bundle/cache.d.ts +92 -0
- package/dist/packages/work/src/bundle/cache.js +338 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +87 -0
- package/dist/packages/work/src/bundle/fetch.js +345 -0
- package/dist/packages/work/src/bundle/types.d.ts +164 -0
- package/dist/packages/work/src/bundle/types.js +1 -0
- package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
- package/dist/packages/work/src/consumed-verifier.js +205 -0
- package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
- package/dist/packages/work/src/credentials/owenloop.js +28 -0
- package/dist/packages/work/src/credentials/reader.d.ts +36 -0
- package/dist/packages/work/src/credentials/reader.js +32 -0
- package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
- package/dist/packages/work/src/credentials/resolve.js +56 -0
- package/dist/packages/work/src/exec/instructions.d.ts +99 -0
- package/dist/packages/work/src/exec/instructions.js +323 -0
- package/dist/packages/work/src/exec/loop.d.ts +40 -0
- package/dist/packages/work/src/exec/loop.js +332 -0
- package/dist/packages/work/src/exec/payload.d.ts +29 -0
- package/dist/packages/work/src/exec/payload.js +54 -0
- package/dist/packages/work/src/exec/receipt.d.ts +41 -0
- package/dist/packages/work/src/exec/receipt.js +32 -0
- package/dist/packages/work/src/exec/runner.d.ts +71 -0
- package/dist/packages/work/src/exec/runner.js +256 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +134 -0
- package/dist/packages/work/src/harness/claude.d.ts +140 -0
- package/dist/packages/work/src/harness/claude.js +837 -0
- package/dist/packages/work/src/harness/codex.d.ts +111 -0
- package/dist/packages/work/src/harness/codex.js +1024 -0
- package/dist/packages/work/src/harness/contract.d.ts +308 -0
- package/dist/packages/work/src/harness/contract.js +32 -0
- package/dist/packages/work/src/harness/fake.d.ts +59 -0
- package/dist/packages/work/src/harness/fake.js +91 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +351 -0
- package/dist/packages/work/src/harness/permissions.d.ts +75 -0
- package/dist/packages/work/src/harness/permissions.js +182 -0
- package/dist/packages/work/src/harness/registry.d.ts +47 -0
- package/dist/packages/work/src/harness/registry.js +45 -0
- package/dist/packages/work/src/harness/session-store.d.ts +181 -0
- package/dist/packages/work/src/harness/session-store.js +523 -0
- package/dist/packages/work/src/harness/types.d.ts +29 -0
- package/dist/packages/work/src/harness/types.js +14 -0
- package/dist/packages/work/src/harnesses.d.ts +38 -0
- package/dist/packages/work/src/harnesses.js +38 -0
- package/dist/packages/work/src/hold/loop.d.ts +36 -0
- package/dist/packages/work/src/hold/loop.js +23 -0
- package/dist/packages/work/src/hold/mcp.d.ts +75 -0
- package/dist/packages/work/src/hold/mcp.js +264 -0
- package/dist/packages/work/src/hub/client.d.ts +23 -0
- package/dist/packages/work/src/hub/client.js +91 -0
- package/dist/packages/work/src/hub/types.d.ts +326 -0
- package/dist/packages/work/src/hub/types.js +26 -0
- package/dist/packages/work/src/lease/loop.d.ts +94 -0
- package/dist/packages/work/src/lease/loop.js +277 -0
- package/dist/packages/work/src/main.d.ts +1 -0
- package/dist/packages/work/src/main.js +48 -0
- package/dist/packages/work/src/mcp/server.d.ts +125 -0
- package/dist/packages/work/src/mcp/server.js +320 -0
- package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
- package/dist/packages/work/src/owenloop-bin.js +18 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +124 -0
- package/dist/packages/work/src/roles/agent-run.js +529 -0
- package/dist/packages/work/src/roles/exec.d.ts +48 -0
- package/dist/packages/work/src/roles/exec.js +228 -0
- package/dist/packages/work/src/roles/hold.d.ts +72 -0
- package/dist/packages/work/src/roles/hold.js +363 -0
- package/dist/packages/work/src/roles/join.d.ts +18 -0
- package/dist/packages/work/src/roles/join.js +204 -0
- package/dist/packages/work/src/roles/lint.d.ts +58 -0
- package/dist/packages/work/src/roles/lint.js +234 -0
- package/dist/packages/work/src/roles/prepare.d.ts +1 -0
- package/dist/packages/work/src/roles/prepare.js +249 -0
- package/dist/packages/work/src/roles/release.d.ts +48 -0
- package/dist/packages/work/src/roles/release.js +137 -0
- package/dist/packages/work/src/roles/sessions.d.ts +61 -0
- package/dist/packages/work/src/roles/sessions.js +180 -0
- package/dist/packages/work/src/roles/settings.d.ts +6 -0
- package/dist/packages/work/src/roles/settings.js +71 -0
- package/dist/packages/work/src/roles/shift.d.ts +13 -0
- package/dist/packages/work/src/roles/shift.js +250 -0
- package/dist/packages/work/src/roles/signals.d.ts +55 -0
- package/dist/packages/work/src/roles/signals.js +62 -0
- package/dist/packages/work/src/settings/provision.d.ts +21 -0
- package/dist/packages/work/src/settings/provision.js +47 -0
- package/dist/packages/work/src/settings/settings.d.ts +136 -0
- package/dist/packages/work/src/settings/settings.js +155 -0
- package/dist/packages/work/src/shift/client.d.ts +24 -0
- package/dist/packages/work/src/shift/client.js +124 -0
- package/dist/packages/work/src/shift/loop.d.ts +131 -0
- package/dist/packages/work/src/shift/loop.js +751 -0
- package/dist/packages/work/src/shift/protocol.d.ts +95 -0
- package/dist/packages/work/src/shift/protocol.js +24 -0
- package/dist/packages/work/src/shift/routing.d.ts +35 -0
- package/dist/packages/work/src/shift/routing.js +50 -0
- package/dist/packages/work/src/shift/runtime.d.ts +45 -0
- package/dist/packages/work/src/shift/runtime.js +337 -0
- package/dist/packages/work/src/shift/server.d.ts +23 -0
- package/dist/packages/work/src/shift/server.js +716 -0
- package/dist/packages/work/src/shift/spawn.d.ts +109 -0
- package/dist/packages/work/src/shift/spawn.js +158 -0
- package/dist/packages/work/src/shift/state.d.ts +79 -0
- package/dist/packages/work/src/shift/state.js +385 -0
- package/dist/packages/work/src/submit-proof.d.ts +36 -0
- package/dist/packages/work/src/submit-proof.js +93 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/src/add.d.ts +189 -0
- package/dist/src/add.js +300 -0
- package/dist/src/archive.d.ts +97 -0
- package/dist/src/archive.js +591 -0
- package/dist/src/bundle/index.d.ts +64 -0
- package/dist/src/bundle/index.js +508 -0
- package/dist/src/bundle/manifest.d.ts +50 -0
- package/dist/src/bundle/manifest.js +435 -0
- package/dist/src/bundle/runtime.d.ts +26 -0
- package/dist/src/bundle/runtime.js +64 -0
- package/dist/src/bundle/tar.d.ts +62 -0
- package/dist/src/bundle/tar.js +238 -0
- package/dist/src/bundle/types.d.ts +105 -0
- package/dist/src/bundle/types.js +21 -0
- package/dist/{cli.d.ts → src/cli.d.ts} +92 -7
- package/dist/src/cli.js +5968 -0
- package/dist/{credentials.d.ts → src/credentials.d.ts} +22 -15
- package/dist/{credentials.js → src/credentials.js} +35 -31
- package/dist/src/crypto/allowed-signers.d.ts +68 -0
- package/dist/src/crypto/allowed-signers.js +307 -0
- package/dist/src/crypto/canonical.d.ts +8 -0
- package/dist/src/crypto/canonical.js +92 -0
- package/dist/src/crypto/chain.d.ts +65 -0
- package/dist/src/crypto/chain.js +377 -0
- package/dist/src/crypto/dsse.d.ts +209 -0
- package/dist/src/crypto/dsse.js +282 -0
- package/dist/src/crypto/enrollment.d.ts +78 -0
- package/dist/src/crypto/enrollment.js +186 -0
- package/dist/src/crypto/index.d.ts +48 -0
- package/dist/src/crypto/index.js +44 -0
- package/dist/src/crypto/keys.d.ts +258 -0
- package/dist/src/crypto/keys.js +908 -0
- package/dist/src/crypto/org-root.d.ts +33 -0
- package/dist/src/crypto/org-root.js +78 -0
- package/dist/src/crypto/origin-rules.d.ts +56 -0
- package/dist/src/crypto/origin-rules.js +143 -0
- package/dist/src/crypto/policy-floor.d.ts +98 -0
- package/dist/src/crypto/policy-floor.js +353 -0
- package/dist/src/crypto/records.d.ts +316 -0
- package/dist/src/crypto/records.js +157 -0
- package/dist/src/crypto/scope.d.ts +49 -0
- package/dist/src/crypto/scope.js +83 -0
- package/dist/src/crypto/ssh.d.ts +171 -0
- package/dist/src/crypto/ssh.js +396 -0
- package/dist/src/crypto/submission.d.ts +33 -0
- package/dist/src/crypto/submission.js +47 -0
- package/dist/src/crypto/trust-roots.d.ts +29 -0
- package/dist/src/crypto/trust-roots.js +39 -0
- package/dist/src/crypto/verify-consumed.d.ts +67 -0
- package/dist/src/crypto/verify-consumed.js +259 -0
- package/dist/src/crypto/verify-origin.d.ts +50 -0
- package/dist/src/crypto/verify-origin.js +151 -0
- package/dist/src/crypto/verify-publication.d.ts +60 -0
- package/dist/src/crypto/verify-publication.js +150 -0
- package/dist/{defs.d.ts → src/defs.d.ts} +24 -1
- package/dist/{defs.js → src/defs.js} +181 -61
- package/dist/{engine.d.ts → src/engine.d.ts} +105 -9
- package/dist/{engine.js → src/engine.js} +251 -47
- package/dist/{factory.d.ts → src/factory.d.ts} +16 -0
- package/dist/{factory.js → src/factory.js} +16 -4
- package/dist/src/global-config.d.ts +59 -0
- package/dist/src/global-config.js +84 -0
- package/dist/{hub.d.ts → src/hub.d.ts} +280 -31
- package/dist/{hub.js → src/hub.js} +493 -52
- package/dist/src/index.d.ts +47 -0
- package/dist/src/index.js +41 -0
- package/dist/src/install.d.ts +538 -0
- package/dist/src/install.js +1981 -0
- package/dist/src/lock.d.ts +38 -0
- package/dist/src/lock.js +325 -0
- package/dist/src/mcp/serve.d.ts +109 -0
- package/dist/{mcp → src/mcp}/serve.js +335 -75
- package/dist/{mcp → src/mcp}/server.d.ts +6 -9
- package/dist/{mcp → src/mcp}/server.js +18 -10
- package/dist/{model.d.ts → src/model.d.ts} +15 -0
- package/dist/{model.js → src/model.js} +112 -2
- package/dist/src/order-resolver.d.ts +184 -0
- package/dist/src/order-resolver.js +252 -0
- package/dist/src/package-version.d.ts +10 -0
- package/dist/src/package-version.js +42 -0
- package/dist/{paths.d.ts → src/paths.d.ts} +14 -1
- package/dist/{paths.js → src/paths.js} +18 -0
- package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
- package/dist/src/schemas/index.d.ts +1416 -0
- package/dist/src/schemas/index.js +31 -0
- package/dist/src/schemas/order.v1.schema.json +106 -0
- package/dist/src/schemas/origin.v1.schema.json +68 -0
- package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
- package/dist/src/schemas/publication.v1.schema.json +31 -0
- package/dist/src/schemas/revocation.v1.schema.json +39 -0
- package/dist/src/schemas/submission.v1.schema.json +61 -0
- package/dist/src/store/def-source.d.ts +52 -0
- package/dist/src/store/def-source.js +335 -0
- package/dist/src/store/index-file.d.ts +69 -0
- package/dist/src/store/index-file.js +151 -0
- package/dist/src/store/index.d.ts +27 -0
- package/dist/src/store/index.js +22 -0
- package/dist/src/store/ingestor.d.ts +43 -0
- package/dist/src/store/ingestor.js +211 -0
- package/dist/src/store/install.d.ts +228 -0
- package/dist/src/store/install.js +555 -0
- package/dist/src/store/instruction-source.d.ts +49 -0
- package/dist/src/store/instruction-source.js +298 -0
- package/dist/src/store/origin-evidence.d.ts +21 -0
- package/dist/src/store/origin-evidence.js +66 -0
- package/dist/src/store/pre-commit-verifier.d.ts +68 -0
- package/dist/src/store/pre-commit-verifier.js +418 -0
- package/dist/src/store/resolve.d.ts +138 -0
- package/dist/src/store/resolve.js +363 -0
- package/dist/src/store/types.d.ts +288 -0
- package/dist/src/store/types.js +356 -0
- package/dist/{types.d.ts → src/types.d.ts} +58 -24
- package/dist/{untar.d.ts → src/untar.d.ts} +8 -23
- package/dist/src/untar.js +38 -0
- package/dist/{util.d.ts → src/util.d.ts} +3 -2
- package/dist/{util.js → src/util.js} +3 -2
- package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
- package/dist/{owenwork.js → src/work-settings.js} +27 -27
- package/docs/agent-runner.md +86 -0
- package/docs/authoring.md +150 -59
- package/docs/bundles.md +250 -0
- package/docs/cli.md +1758 -163
- package/docs/crypto.md +816 -0
- package/docs/design.md +374 -52
- package/docs/embedding.md +135 -27
- package/docs/wire-contracts.md +380 -0
- package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
- package/examples/workflows/compile-dev-playbook.yaml +338 -0
- package/examples/workflows/judges/gate-sharpness.md +39 -0
- package/examples/workflows/judges/security.md +34 -0
- package/package.json +22 -8
- package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
- package/plugins/claude-code/plugin/.mcp.json +14 -0
- package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
- package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
- package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
- package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
- package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
- package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
- package/plugins/codex/.agents/plugins/marketplace.json +21 -0
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
- package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
- package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
- package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
- package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
- package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
- package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
- package/dist/add.d.ts +0 -384
- package/dist/add.js +0 -834
- package/dist/cli.js +0 -3270
- package/dist/index.d.ts +0 -32
- package/dist/index.js +0 -23
- package/dist/lock.d.ts +0 -80
- package/dist/lock.js +0 -217
- package/dist/mcp/serve.d.ts +0 -84
- package/dist/untar.js +0 -164
- /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
- /package/dist/{schema.js → src/schema.js} +0 -0
- /package/dist/{store.d.ts → src/store.d.ts} +0 -0
- /package/dist/{store.js → src/store.js} +0 -0
- /package/dist/{types.js → src/types.js} +0 -0
package/docs/bundles.md
ADDED
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
# `.wnlp` bundle format
|
|
2
|
+
|
|
3
|
+
A `.wnlp` file packages one versioned package namespace, one or more named workflow definitions, and the regular files those definitions reference. The physical format is a gzip-compressed POSIX/PAX tar archive. Packing the same source bytes and canonical executable-bit choices produces identical archive bytes.
|
|
4
|
+
|
|
5
|
+
The bundle APIs are independent of the local workflow store and the network:
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import { digestBundle, inspectBundle, packBundle, unpackBundle } from 'owenloop';
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
The command-line equivalents are documented in [`docs/cli.md`](cli.md#bundles).
|
|
12
|
+
|
|
13
|
+
## Source layout
|
|
14
|
+
|
|
15
|
+
A source directory must contain `bundle.yaml` and every path listed by the manifest's `workflows` map. Workflow paths may be at the source root or below a subdirectory. For example:
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
report/
|
|
19
|
+
├── bundle.yaml
|
|
20
|
+
├── workflows/
|
|
21
|
+
│ ├── delivery.yaml
|
|
22
|
+
│ ├── init.yaml
|
|
23
|
+
│ └── instructions/
|
|
24
|
+
│ └── writer.md
|
|
25
|
+
└── schemas/
|
|
26
|
+
└── findings.json
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The packer recursively includes regular files below the source directory. The packer refuses symlinks, device files, FIFOs, sockets, and any other non-regular filesystem node. Directory entries are implied by file paths and are not stored in the archive.
|
|
30
|
+
|
|
31
|
+
Each workflow definition is authoritative for that workflow's execution. A `bodyFile` reference in a step or judge is relative to the directory containing that workflow YAML file. For example, `bodyFile: instructions/writer.md` in `workflows/delivery.yaml` resolves to `workflows/instructions/writer.md`. The authored `bodyFile` and the resolved archive path must both satisfy the canonical bundle path safety policy. The packer and strict archive reader apply the same rule before parsing the workflow.
|
|
32
|
+
|
|
33
|
+
## `bundle.yaml`
|
|
34
|
+
|
|
35
|
+
The manifest is a package-only document. The manifest does not declare workers, commands, interpreters, scripts, or other execution behavior. Unknown keys, aliases, merge keys, tagged nodes, duplicate keys, non-string mapping keys, and invalid YAML are rejected.
|
|
36
|
+
|
|
37
|
+
The v2 shape is:
|
|
38
|
+
|
|
39
|
+
```yaml
|
|
40
|
+
formatVersion: 2
|
|
41
|
+
package:
|
|
42
|
+
name: owenloop-delivery
|
|
43
|
+
version: 1.0.0
|
|
44
|
+
runtime:
|
|
45
|
+
minVersion: "0.5.1"
|
|
46
|
+
features:
|
|
47
|
+
- harness-policy-enforcement.v1
|
|
48
|
+
- native-judge-policy-inheritance.v1
|
|
49
|
+
workflows:
|
|
50
|
+
delivery: "workflows/delivery.yaml"
|
|
51
|
+
init: "workflows/init.yaml"
|
|
52
|
+
default: "delivery"
|
|
53
|
+
platforms:
|
|
54
|
+
- darwin-arm64
|
|
55
|
+
- linux-amd64
|
|
56
|
+
integrity:
|
|
57
|
+
algorithm: sha256
|
|
58
|
+
files:
|
|
59
|
+
workflows/delivery.yaml: "<64 lowercase hex characters>"
|
|
60
|
+
workflows/init.yaml: "<64 lowercase hex characters>"
|
|
61
|
+
workflows/instructions/writer.md: "<64 lowercase hex characters>"
|
|
62
|
+
schemas/findings.json: "<64 lowercase hex characters>"
|
|
63
|
+
capabilities:
|
|
64
|
+
commands:
|
|
65
|
+
- git
|
|
66
|
+
lock:
|
|
67
|
+
example/research@1.0.0: "<64 lowercase hex characters>"
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The following rules apply:
|
|
71
|
+
|
|
72
|
+
- `formatVersion` is exactly `2`. A v1 manifest is not accepted; there is no compatibility parser.
|
|
73
|
+
- `package.name` is a portable package namespace. The default store coordinate for the package is `package.name/package.name@package.version`; an explicit store namespace override may replace the first component. A workflow definition name is not the package name.
|
|
74
|
+
- `package.version` is a non-empty printable ASCII version string without path separators.
|
|
75
|
+
- `runtime` is optional. When present, `runtime` is a closed mapping that contains `minVersion`, `features`, or both; `runtime: {}` is invalid. Runtime requirements are described in [Runtime compatibility](#runtime-compatibility).
|
|
76
|
+
- `workflows` is a non-empty map from workflow names to archive-relative YAML paths. Each workflow name matches `/^[a-z][a-z0-9-]*$/`. Each path must pass the canonical bundle path safety policy, and two workflow names may not point to the same path.
|
|
77
|
+
- A workflow file's `name:` must equal the workflow map key. For example, `workflows.delivery` must point to a file containing `name: delivery`.
|
|
78
|
+
- An installed workflow is addressable from `calls:` by the qualified name `<package>/<workflow>`. A bare `calls: <workflow>` inside a CAS-installed bundle is resolved to a sibling from that same bundle; it does not search unrelated bundles for a same-named workflow. An exact versioned `calls: namespace/name@version` resolves through the verified store-index coordinate to the bundle's selected default workflow, then the engine checks the matching `lock` digest before creating the child.
|
|
79
|
+
- `default` is optional. When present, `default` must be one of the workflow map keys. When absent, a single-workflow package has that one workflow as its implicit default. A package with two or more workflows has no implicit default: the versioned coordinate is not registered as a callable target, while explicit `<package>/<workflow>` targets remain available.
|
|
80
|
+
- `platforms` is a duplicate-free list of portable selector strings. The list is advisory; platform policy is outside the package parser.
|
|
81
|
+
- `integrity.algorithm` is exactly `sha256`.
|
|
82
|
+
- `integrity.files` contains one lowercase 64-hex SHA-256 digest for every regular archive file except `bundle.yaml`. The packer regenerates this map from the source bytes and does not edit the source manifest. Excluding `bundle.yaml` avoids a recursive self-hash; the def digest still covers the complete canonical tar, including `bundle.yaml`.
|
|
83
|
+
- `capabilities` contains requested capability classes and values. The manifest does not grant capabilities.
|
|
84
|
+
- `lock` maps exact versioned `namespace/name@version` call references to lowercase 64-hex **bundle digests**. Every explicit versioned `calls:` target in every workflow must have a matching lock key. A bare same-bundle call has no lock entry: its pin is the containing bundle's own digest. The runtime compares bundle digests at child spawn; it does not compare this lock value with a per-workflow instruction digest.
|
|
85
|
+
|
|
86
|
+
Canonical manifest serialization uses the fixed top-level order `formatVersion`, `package`, optional `runtime`, `workflows`, optional `default`, `platforms`, `integrity`, `capabilities`, `lock`. Runtime fields use the order `minVersion`, then `features`; feature identifiers are sorted by ascending UTF-8 bytes. Other mapping keys and list values use their defined canonical order. Strings use JSON-style double quotes, indentation is two spaces, and the document has exactly one final newline. Inspection rejects a manifest that parses correctly but is not in that canonical byte form.
|
|
87
|
+
|
|
88
|
+
## Runtime compatibility
|
|
89
|
+
|
|
90
|
+
The optional `runtime` mapping declares requirements that the Owenloop process must satisfy before Owenloop returns usable workflow definitions or instructions:
|
|
91
|
+
|
|
92
|
+
```yaml
|
|
93
|
+
runtime:
|
|
94
|
+
minVersion: "0.5.1"
|
|
95
|
+
features:
|
|
96
|
+
- harness-policy-enforcement.v1
|
|
97
|
+
- native-judge-policy-inheritance.v1
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The mapping is strict and closed. Unknown keys are rejected. At least one of `minVersion` and `features` is required.
|
|
101
|
+
|
|
102
|
+
- `minVersion` is exactly one canonical strict SemVer value. Ranges, a leading `v`, surrounding whitespace, and non-canonical forms are invalid. Owenloop compares the running package version with standard SemVer prerelease precedence; build metadata does not affect precedence.
|
|
103
|
+
- `features` is a non-empty, duplicate-free sequence. Each identifier is at most 128 UTF-8 bytes and matches `/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*\.v[1-9][0-9]*$/`: lowercase portable segments ending in a positive, non-zero-padded `.vN` version.
|
|
104
|
+
- When both fields are present, both requirements must pass. The fields use AND semantics, not alternatives.
|
|
105
|
+
|
|
106
|
+
This Owenloop release advertises exactly these feature identifiers:
|
|
107
|
+
|
|
108
|
+
- `harness-policy-enforcement.v1`
|
|
109
|
+
- `native-judge-policy-inheritance.v1`
|
|
110
|
+
|
|
111
|
+
The running version comes from Owenloop's production `packageVersion()` source. A production build that cannot read a valid package version uses the `0.0.0` sentinel. The sentinel fails every declared `minVersion`, including `minVersion: "0.0.0"`, and the refusal tells the operator to install or upgrade Owenloop. The sentinel may still satisfy a feature-only declaration because feature support is evaluated independently.
|
|
112
|
+
|
|
113
|
+
Malformed runtime declarations fail with `BundleError.code === "MANIFEST_ERROR"`. A well-formed declaration that requires a newer Owenloop version or an unsupported feature fails with `BundleError.code === "RUNTIME_INCOMPATIBLE"`. Runtime-incompatible source bundles cannot be packed; runtime-incompatible packed bundles cannot be inspected, unpacked, installed, loaded as instructions, or executed. Definition listing and status discovery retain their existing fail-open behavior: they warn, skip the incompatible installed object, and continue loading unrelated definitions. Instruction and execution resolution fail closed before a command process, agent harness, or provider starts.
|
|
114
|
+
|
|
115
|
+
An absent `runtime` field preserves the previous canonical manifest bytes and bundle digest exactly. Adding, changing, or removing a present runtime declaration changes `bundle.yaml`, the canonical tar bytes, and therefore the content-addressed bundle digest. Readers that predate the runtime contract reject a present `runtime` key as an unknown top-level manifest key; authors must set requirements only when every required consumer supports this contract.
|
|
116
|
+
|
|
117
|
+
## Canonical archive
|
|
118
|
+
|
|
119
|
+
The def digest is the lowercase SHA-256 hash of the exact **uncompressed canonical tar bytes**. The gzip bytes are a transport encoding and are not the bundle identity.
|
|
120
|
+
|
|
121
|
+
For every regular file:
|
|
122
|
+
|
|
123
|
+
- Archive paths use `/` separators and are sorted by ascending UTF-8 bytes. A backslash is rejected as a character in a canonical bundle path; the reader never treats a backslash as an alternate separator.
|
|
124
|
+
- Empty paths, NUL bytes, absolute paths, Windows drive paths, UNC paths, and `.` or `..` path segments are rejected.
|
|
125
|
+
- A regular-file path may not be a complete-segment prefix of another regular-file path. For example, one archive cannot contain both `a` and `a/b` because `a` cannot be both a regular file and a parent directory.
|
|
126
|
+
- The canonical `.wnlp` path policy is deliberately stricter than the GitHub archive compatibility policy used by `owenloop add`. GitHub archive handling keeps its separate compatibility rules; ordinary backslashes that policy accepts are still invalid in canonical bundle paths.
|
|
127
|
+
- `uid` and `gid` are `0`.
|
|
128
|
+
- `uname` and `gname` are empty.
|
|
129
|
+
- `mtime` is `0`.
|
|
130
|
+
- Mode is `0644`, or `0755` when any source execute bit is set. Other mode bits do not affect the output.
|
|
131
|
+
- Short UTF-8 paths use canonical USTAR headers.
|
|
132
|
+
- Paths that do not fit the USTAR name field use one deterministic POSIX PAX `path` record in a `PaxHeader` entry.
|
|
133
|
+
- Header fields use canonical zero-padded octal values, USTAR magic `ustar\0`, version `00`, and zeroed link, device, and prefix fields.
|
|
134
|
+
- Each regular archive file uses typeflag `0`.
|
|
135
|
+
- Every entry's data padding, including the padding after a `PaxHeader` data record, is zero-filled.
|
|
136
|
+
- The archive ends with exactly two zero blocks and no bytes after the terminator.
|
|
137
|
+
|
|
138
|
+
The gzip wrapper uses compression level 9 and has no optional filename, comment, or extra fields. Gzip mtime bytes are zero, and gzip header byte 9 (the OS byte) is explicitly forced to zero so Darwin and Linux produce the same bytes.
|
|
139
|
+
|
|
140
|
+
The canonical tar contains regular-file entries only. Parent directories are implied by `/`-separated file paths and are never emitted as tar entries. The strict reader rejects archive symlink, hardlink, device, FIFO, socket, directory, and unknown entry types. The packer rejects source symlinks and non-regular filesystem nodes. Absolute paths, `.` segments, and `..` traversal are refused rather than normalized.
|
|
141
|
+
|
|
142
|
+
The strict reader is as constrained as the writer. Every byte range parsed by the reader is limited to the exact form emitted by the canonical writer, including regular-file data padding and PAX-header data padding, which must be zero. This closes padding malleability: attacker-chosen bytes cannot sit inside the digest-covered tar while remaining absent from every per-file hash.
|
|
143
|
+
|
|
144
|
+
## Reading and extraction safety
|
|
145
|
+
|
|
146
|
+
`inspectBundle` and `unpackBundle` apply bounded compressed size, expanded size, tar-header count, per-file size, and path length limits before returning or writing file data. Strict readers reject malformed checksums and octal fields, truncated headers or data, malformed or dangling PAX metadata, duplicate paths, complete-segment file-prefix collisions, backslashes, unsupported entry types, non-canonical headers, unsorted effective paths, trailing bytes, missing manifests, invalid manifests, runtime-incompatible manifests, missing or invalid workflows, unsafe workflow paths, workflow validation failures, and integrity mismatches.
|
|
147
|
+
|
|
148
|
+
`parseManifestBytes` is the common runtime-admission boundary. Source packing, packed inspection, unpacking, workflow-store installation, installed-object verification, definition discovery, instruction lookup, and worker execution all pass through that boundary before returning usable definitions or instructions.
|
|
149
|
+
|
|
150
|
+
`unpackBundle` validates the complete archive before filesystem writes. The destination must not already exist. The unpacker checks every existing destination ancestor and rejects operator-created symlinks, then writes into a fresh sibling staging directory. The staging directory is renamed into place only after all files are written; failed unpack operations remove staging and leave the destination absent.
|
|
151
|
+
|
|
152
|
+
## Installed-object verification on read
|
|
153
|
+
|
|
154
|
+
The store's bundle ingestor verifies an installed object again every time a resolver needs its contents. The verifier safely enumerates every installed regular file, reads each file once, and preserves the existing detailed refusals for missing integrity-listed files, changed file digests, unlisted extra files, unsafe paths, symlinks, devices, FIFOs, and other wrong filesystem types.
|
|
155
|
+
|
|
156
|
+
After the per-file checks pass, the verifier reconstructs the complete canonical uncompressed tar from the installed files, including `bundle.yaml`. Installed non-executable files reconstruct as canonical mode `0644`; files with any execute bit reconstruct as `0755`. The SHA-256 digest of those canonical tar bytes must equal the object's `objects/sha256/<digest>` content address. This complete-object check covers runtime-only changes and removal of the runtime declaration even though `integrity.files` excludes `bundle.yaml` to avoid a recursive self-hash.
|
|
157
|
+
|
|
158
|
+
A store index entry records the sorted workflow names alongside the package coordinate and bundle digest. Executable definition discovery preserves each verified coordinate and fails closed on corrupt index or object state; read-only status inspection can skip damage only while reporting that its result is incomplete. Runtime instruction resolution reads the verified installed manifest and loads every listed workflow; a requested instruction digest may match any workflow in the installed object. A verification failure prevents the object from populating usable definition and instruction caches. Cache hits are re-verified, and a later failure evicts the cached object.
|
|
159
|
+
|
|
160
|
+
This check is separate from the read-only file modes applied during install. Installation maps canonical `0644` files to read-only `0444` and canonical `0755` files to read/execute-only `0555`, preserving the executable distinction needed to reconstruct identity. Changing an installed object on disk therefore produces an integrity refusal at resolution time, not a best-effort read and not an `unknown-digest` fallback.
|
|
161
|
+
|
|
162
|
+
An executable file installed by an older Owenloop release may already have lost its execute bit because older hardening mapped every regular file to `0444`. Reinstalling the exact original `.wnlp` is a supported atomic repair for that same-digest object. Owenloop first applies strict archive parsing, manifest and runtime admission, configured signature and policy verification, per-file integrity verification, and canonical digest verification to the supplied archive. Owenloop then reconstructs and completely verifies a clean staged object before replacing the broken destination through the normal journaled directory swap. The broken object's bytes are never reused. The prior object remains as the swap backup until the unchanged same-digest index state is durably committed; a failed repair restores the recoverable prior object and index state. A successful repair preserves the existing coordinate-to-digest mapping, and a later reinstall follows normal idempotent deduplication.
|
|
163
|
+
|
|
164
|
+
## Bundle assets during execution
|
|
165
|
+
|
|
166
|
+
When a command or agent step resolves its definition from an installed bundle,
|
|
167
|
+
owenloop sets `OWENLOOP_BUNDLE_DIR` to the verified installed object directory.
|
|
168
|
+
The directory is the bundle root, so a command can reference a shipped script with
|
|
169
|
+
an explicit quoted path:
|
|
170
|
+
|
|
171
|
+
```sh
|
|
172
|
+
node "$OWENLOOP_BUNDLE_DIR/scripts/provision.mjs"
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
owenloop sets `OWENLOOP_BUNDLE_DIR` only for definitions with installed-bundle
|
|
176
|
+
provenance. A definition without bundle provenance receives no value. Bundle
|
|
177
|
+
scripts must treat an unset or empty variable as a hard error and report a
|
|
178
|
+
message such as `this workflow must run from an installed bundle`; owenloop does
|
|
179
|
+
not synthesize a fallback directory.
|
|
180
|
+
|
|
181
|
+
Command and agent children receive two engine-derived identity variables:
|
|
182
|
+
`OWENLOOP_WORKFLOW` contains the workflow-instance id, and `OWENLOOP_RUN`
|
|
183
|
+
contains the run id. Both variables are always set, including for definitions
|
|
184
|
+
without bundle provenance. A command can read them directly:
|
|
185
|
+
|
|
186
|
+
```sh
|
|
187
|
+
printf '%s %s\n' "$OWENLOOP_WORKFLOW" "$OWENLOOP_RUN"
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
For agent children, admitting a name to `ADMITTED_OWENLOOP_KEYS` is only a
|
|
191
|
+
filter permission: `filterOwenloopEnv` permits an existing value through, but
|
|
192
|
+
does not make that value authoritative. `agent-run` sets both variables from
|
|
193
|
+
the worker's own engine-derived target before starting the child and overwrites
|
|
194
|
+
ambient values, so a nested agent receives its own identity rather than a
|
|
195
|
+
stale parent value.
|
|
196
|
+
|
|
197
|
+
Run identity is safe to expose because the engine derives it from the worker's
|
|
198
|
+
own `--order` argument. Consumed artifact values are attacker-influenceable and
|
|
199
|
+
are not exposed, and command text is not interpolated; no consume-side gate
|
|
200
|
+
exists for either capability.
|
|
201
|
+
|
|
202
|
+
`OWENLOOP_BUNDLE_DIR` is read-only. Workers must never write into the directory.
|
|
203
|
+
The workflow store is content-addressed and verifies the installed object again
|
|
204
|
+
when a resolver reads it. A write changes the object bytes, so the next read
|
|
205
|
+
fails the digest or file-integrity check instead of executing the modified
|
|
206
|
+
bundle. Mount or copy enforcement is not part of the current contract;
|
|
207
|
+
documentation is the enforcement boundary for now.
|
|
208
|
+
|
|
209
|
+
## API results
|
|
210
|
+
|
|
211
|
+
`packBundle(sourceDir)` returns:
|
|
212
|
+
|
|
213
|
+
- `bytes`: the complete gzip-compressed `.wnlp` file;
|
|
214
|
+
- `digest`: the canonical uncompressed-tar digest;
|
|
215
|
+
- `manifest`: the canonical manifest archived in `bytes`; and
|
|
216
|
+
- `entries`: sorted path, size, executable-bit, and per-file digest metadata.
|
|
217
|
+
|
|
218
|
+
`inspectBundle(bytes)` returns the digest, runtime-admitted validated manifest, and entry metadata without writing files. `unpackBundle(bytes, destination)` returns the same inspection result plus the absolute materialized destination path.
|
|
219
|
+
|
|
220
|
+
`digestBundle(bytes)` is the deliberate identity-only exception to runtime admission. The function enforces the compressed and expanded size limits, inflates the gzip payload, and hashes the exact decompressed bytes. The function does not parse or validate a canonical tar and does not parse `bundle.yaml`; therefore `digestBundle` can return a digest for bounded gzip content that is not an admissible bundle, including an archive whose runtime declaration the current Owenloop process cannot satisfy. A successful digest does not mean the content is a canonical tar or that the bundle is admissible for packing, inspection, unpacking, installation, definition loading, instruction lookup, or execution.
|
|
221
|
+
|
|
222
|
+
`owenloop publish` signs exactly `packBundle(sourceDir).digest`: the lowercase 64-hex SHA-256 digest of the uncompressed canonical tar. It does not sign the gzip wrapper bytes or the separate compiled-definition hash used by `push`.
|
|
223
|
+
|
|
224
|
+
All bundle failures are `BundleError` instances with a stable `code` suitable for scripts. The CLI keeps that code in the stderr diagnostic.
|
|
225
|
+
|
|
226
|
+
## Limits
|
|
227
|
+
|
|
228
|
+
The default shared archive limits are:
|
|
229
|
+
|
|
230
|
+
| limit | default |
|
|
231
|
+
|---|---:|
|
|
232
|
+
| compressed input | 256 MiB |
|
|
233
|
+
| expanded tar | 1 GiB |
|
|
234
|
+
| tar headers | 50,000 |
|
|
235
|
+
| one regular file | 100 MiB |
|
|
236
|
+
| one path | 1,024 characters |
|
|
237
|
+
|
|
238
|
+
The in-process APIs accept `limits` overrides through `PackOptions` or `InspectOptions`. Limits apply before archive data is copied or extracted.
|
|
239
|
+
|
|
240
|
+
## Verification example
|
|
241
|
+
|
|
242
|
+
A package can be inspected with both owenloop and a stock tar implementation:
|
|
243
|
+
|
|
244
|
+
```sh
|
|
245
|
+
owenloop bundle inspect ./report-1.2.0.wnlp
|
|
246
|
+
owenloop bundle digest ./report-1.2.0.wnlp
|
|
247
|
+
tar -tzf ./report-1.2.0.wnlp
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
The digest printed by `owenloop bundle digest` is stable across gzip metadata, operating-system, and filesystem timestamp differences when the canonical file bytes and executable-bit choices are unchanged. CI recomputes a checked-in golden vector on both Ubuntu and macOS to guard this cross-platform stability.
|