Shareable reproducible task packages

Shareable reproducible task packages

A Holaryn task package (.sxp) is a portable, inspectable handoff for a task—not merely a
transcript. It can carry the objective and canonical messages, immutable input or artifact
payloads, agent/profile/workflow versions, model constraints, context references, dependency and
permission requirements, budgets, success criteria, prior evidence, provenance, and handoff
references.

Treat every imported package as untrusted. A valid signature proves that the archive has not
changed since a particular publisher key signed it; it does not prove that its instructions,
payloads, dependencies, or requested permissions are safe.

Package kinds

• Template: reusable task definition with no prior results or evidence.
• Snapshot: a task handoff with selected inputs and optional prior results/evidence.
• Diagnostic: a minimized, reviewed reproduction intended for debugging.

All three use manifest version 1.0. Unknown manifest fields, malformed versions, undeclared
payload references, and duplicate success-criterion identifiers are rejected rather than guessed.

The safety model

The package lifecycle has three separate records:

1. Immutable source: the canonical archive, content hashes, signature, declared provenance,
   dependencies, policy requests, and payloads.
2. Local resolution overlay: host-specific model, path, account, and opaque SecretRef mappings.
   Forking or remapping an overlay never rewrites the source package or its provenance.
3. Activation plan: a fresh compatibility, dependency, trust, permission, and data summary.
   Import and preflight default to dry-run; execution remains sandboxed and explicit.

Raw credentials, cookies, tokens, or account credentials are not valid portability mechanisms.
Declare secret-slot and account-slot dependencies. Resolve a secret slot only to an opaque
identifier such as:

secretref:v1:12345678-1234-5678-1234-567812345678

The export scanner is defense in depth, not permission to export unreviewed private data. It scans
the manifest and source inventory for configured secret canaries, credential-like strings, private
or credential-bearing URLs, identities, local paths, sensitive metadata, and uninspectable binary
content. Reports contain bounded redacted samples, never the matched canary value. Every finding
must have an explicit redact, exclude, or include decision. Secret-like findings cannot be
included raw.

Manifest version 1

Print the authoritative JSON Schema from the installed build:

holaryn task-package schema

The main fields are:

The export plan is a JSON object with a manifest plus local sources. A source has a logical
portable path and a local source_path; the local path itself is never serialized into the
package. Export computes each PackageItem, SHA-256 digest, size, and content-addressed blob path.

A runnable offline example lives at
docs/examples/task-package/reference-plan.json.

Review and export with the CLI

Run the example from its directory so its relative source path resolves:

Set-Location docs\examples\task-package

holaryn task-package scan reference-plan.json --report report.json
holaryn task-package prepare-review report.json --output review.json --reviewed-by release-reviewer

Open both files. report.json shows every source, byte count, media type, content digest, finding,
redacted sample, and suggested action. review.json binds decisions to both the request digest and
report digest. Every generated value starts with CHOOSE: and is intentionally invalid for
export. Replace each one deliberately with redact, exclude, or include; do not treat the
suggestion as review.

For a known test token or secret, provide only the environment-variable name:

$env:HOLARYN_PACKAGE_CANARY = "synthetic-value-used-only-for-export-testing"
holaryn task-package scan reference-plan.json --report report.json `
  --secret-canary-env HOLARYN_PACKAGE_CANARY

Export re-reads and re-scans the exact plan and sources. It fails if the request, report, review,
source content, or canary set is stale:

holaryn task-package export reference-plan.json `
  --report report.json `
  --review review.json `
  --output documented-reference.sxp

Signing

Generate an Ed25519 publisher key pair once. Existing key files are never overwritten:

holaryn task-package keygen `
  --private-key "$env:USERPROFILE\.holaryn\publisher-private.pem" `
  --public-key "$env:USERPROFILE\.holaryn\publisher-public.pem"

For a password-protected private key, put the password in an environment variable and pass its
name, not the value:

holaryn task-package export reference-plan.json `
  --report report.json --review review.json `
  --output documented-reference.sxp `
  --signing-key "$env:USERPROFILE\.holaryn\publisher-private.pem" `
  --key-password-env HOLARYN_SIGNING_KEY_PASSWORD

Keep private keys outside repositories and shared folders. Share the public key over an
independently authenticated channel. Importers opt into local publisher trust with
--trusted-key.

Optional direct-share encryption

Encryption wraps the complete canonical archive with scrypt-derived AES-256-GCM authenticated
encryption. The password is accepted only through a named environment variable:

holaryn task-package export reference-plan.json `
  --report report.json --review review.json `
  --output documented-reference.sxp.enc `
  --encrypt-password-env HOLARYN_PACKAGE_SHARE_PASSWORD

Send the password over a different trusted channel. Encryption does not replace redaction,
signatures, dependency review, or permission review.

Inspect, preflight, and import

Inspection verifies archive structure, bounds, payload hashes, README consistency, and the
signature without modifying local state:

holaryn task-package inspect documented-reference.sxp

To recognize a publisher locally:

holaryn task-package --trusted-key publisher-public.pem inspect documented-reference.sxp

The three honest trust tiers are:

Preflight simulates a clean-profile import and reports all missing, incompatible, unresolved, or
approval-required dependencies in one plan. It does not install, grant, resolve, or execute
anything:

holaryn task-package preflight documented-reference.sxp
holaryn task-package import documented-reference.sxp

Use --password-env HOLARYN_PACKAGE_SHARE_PASSWORD for an encrypted package. Use --inventory to
describe dependencies already installed on the destination. An inventory is a JSON array:

[
  {
    "kind": "model",
    "id": "local-text-model",
    "version": "1.2",
    "digest": null,
    "trusted": true,
    "permissions_approved": false
  }
]

Executable dependency kinds—agents, workflows, tools, extensions, and connectors—must be present,
trusted, and separately permission-approved. A package can declare what it needs but cannot grant
trust, install executable code silently, or inherit the publisher's permissions.

Inspect, fork, and remap an imported package

List packages and copy the complete lowercase SHA-256 archive digest:

holaryn task-package list
holaryn task-package show <digest>
holaryn task-package fork <digest> windows-laptop --from-overlay default

Update the fork with optimistic concurrency. The expected revision prevents one operator from
silently overwriting another operator's resolution:

holaryn task-package remap <digest> `
  --overlay windows-laptop `
  --expected-revision 1 `
  --model primary=local-text-model `
  --path workspace-root=D:\work\reproduction `
  --account issue-account=jira-local-account `
  --secret-slot provider-key=secretref:v1:12345678-1234-5678-1234-567812345678

holaryn task-package dry-run <digest> --overlay windows-laptop --inventory inventory.json

Only declared slots can be remapped. The package's archive bytes, manifest, signature, and
provenance remain identical. The web/desktop Task packages page presents this as one chain of
custody: immutable source, local resolution, then activation gate. Its export panel inventories
every source and requires an explicit action for every scan finding.

Reproduce reference evidence

The documented builtin:package-evidence-v1 workflow is intentionally narrow. It hashes declared
package items in a sandbox and compares structured evidence to the manifest. It does not ask a
model to reproduce byte-identical prose.

After the dry-run plan has no blockers:

holaryn task-package rerun-reference <digest> `
  --overlay windows-laptop `
  --inventory inventory.json `
  --confirm "RUN <digest>"

The exact full digest confirmation prevents accidental activation. A successful result has
"sandboxed": true, "equivalent": true, the criterion ids and observed values, and no
mismatches.

Local registries and handoffs

A filesystem registry provides a deterministic offline adapter for a shared folder or controlled
test fixture:

holaryn task-package registry-publish <digest> --registry-dir D:\holaryn-registry
holaryn task-package registry-import registry:sha256:<digest> `
  --registry-dir D:\holaryn-registry

The reference is content-addressed. Registry import verifies it again before persisting it.
Marketplace/private-registry and issue/annotation handoffs are explicit manifest references with
permission notes; they never transfer credentials or bypass the destination's access check.

The authenticated operator API exposes the same workflow under
/api/operator/task-packages: schema, scan, export, inspect, preflight, import, list/detail,
fork/remap, dry-run, reference rerun, and registry operations. JSON request models reject unknown
fields. Secret, signing-key, and encryption values are accepted only by environment-variable
reference.

Archive layout and portability limits

An unencrypted .sxp is a deterministic ZIP with:

manifest.json
README.md
payload/sha256/<lowercase-sha256>

Entries are sorted, use a fixed timestamp and mode, and are stored without platform-specific
metadata. manifest.json is canonical UTF-8 JSON. README.md is derived from the manifest and
checked during import. Identical reviewed content and signing inputs produce identical archive
bytes.

Default hostile-input limits are:

Import also rejects absolute paths, .., drive prefixes, backslashes, non-canonical names,
duplicate or case-colliding paths, symlinks and special files, encrypted ZIP members, undeclared
entries, duplicate JSON keys, invalid content-addressed paths, and mismatched size/hash data.
Optional direct-share encryption is handled outside the ZIP; traditional ZIP encryption is not
accepted.

Portable references should use a stable id and revision. Local paths and workspace locations
belong in overlays. External resources require a permission note and are rechecked locally. License
and sensitivity declarations travel with each payload, but the receiver remains responsible for
policy and legal review.

Recovery and troubleshooting

• task-package.stale-review: the plan, source bytes, scan report, or canary set changed. Scan
  again and make a new review; do not edit digests by hand.
• Tampered/signature/README/payload error: discard the received copy and obtain it again from
  the publisher. Do not “repair” a signed archive.
• Unsafe path, duplicate path, symlink, archive bomb, or too large: the package is hostile or
  outside supported bounds. It is not partially extracted or imported.
• Missing/incompatible/unresolved dependency: inspect the complete preflight plan, install or
  select a compatible dependency through its normal trusted workflow, then remap and dry-run
  again.
• Approval required: executable content is present but does not have both local trust and
  permission approval. Review it through the ordinary marketplace/extension policy.
• Overlay conflict: reload show, preserve the other operator's revision, and reapply your
  intended mapping against the new revision.
• Wrong encryption password: retrieve the password through the agreed channel. Repeated guesses
  do not alter the package.
• Corrupt local package state: stop the host, preserve the state directory for diagnostics, and
  restore a known-good encrypted-state backup. The immutable source archive can be reimported;
  machine-specific overlays must be restored or recreated.

Import writes package state atomically under the selected Holaryn state directory. A failed
validation leaves no partially activated task. Rollback means stop using or restore the local
overlay/package index; it never means editing the received source archive.