Packages and revisions

A Shiplet is a portable application with a stable collaborative identity. Code and configuration travel in a kernel-authority-free package; the trusted kernel keeps its credentials, grants, and runtime data outside it. Authored files are not automatically secret-scanned.

Safe change lifecycle

Fork → edit → validate → preview → promote → deploy.

Validation never changes the active revision. Rollback activates an earlier known-good package through a new audited operation; it does not rewind runtime state. Export copies code and schema, never Shiplet credentials, grants, state, feedback, or audit history.

Use this lifecycle whether the final target stays on Shiplet-managed hosting or moves to customer-owned infrastructure.

The domain model

Object	Meaning
Shiplet	Logical collaborative object with the stable ID, URL, access, feedback, and revision history.
Package	Portable application definition containing code, schemas, instructions, validation, and provenance.
Draft	Mutable isolated working copy with a base revision and optimistic version.
Revision	Immutable validated package snapshot with digest and parent lineage.
Deployment target	Destination and ownership boundary: managed, customer Cloudflare, temporary claim, or detached.
Deployment	One revision installed on one target.
State namespace	Runtime data scoped to a Shiplet and deployment or active MCP revision; never package content.

Package v1 layout

shiplet.json
artifact/**
widget/**
workflow/schema.json
mcp/manifest.json
mcp/handlers/**
AGENTS.md
validation/manifest.json
provenance.json

The transport media type is application/vnd.shiplet.package+json;version=1. The manifest uses shiplet.package/v1 and shiplet.runtime/v1:

{
  "schemaVersion": "shiplet.package/v1",
  "runtimeCompatibility": "shiplet.runtime/v1",
  "entrypoints": {
    "artifact": "artifact/index.html",
    "widget": "widget/index.html",
    "workflow": "workflow/schema.json",
    "mcp": "mcp/manifest.json",
    "agentInstructions": "AGENTS.md",
    "validation": "validation/manifest.json",
    "provenance": "provenance.json"
  },
  "requestedCapabilities": [],
  "limits": { "fileCount": 32, "fileBytes": 16384, "packageBytes": 65536 },
  "staticFirst": true
}

Every file record includes its POSIX-relative path, media type, utf8 or base64 encoding, content, decoded-byte digest, and size. The deterministic envelope has exactly mediaType, manifest, and files at its root. Absolute paths, dot segments, backslashes, control characters, reserved names, and normalization collisions are rejected.

The source-checkout CLI accepts at most 1,024 files, 4 MiB per file, and a 32 MiB package envelope. Declaring higher manifest limits does not raise these ceilings. The package digest changes when any artifact, widget, workflow, MCP handler, instruction, validation, or provenance byte changes.

Code is not authority

Requested capabilities are declarations, never grants. Shiplet never adds kernel-owned credentials, access grants, sessions, OAuth connections, claims, deployments, customer state, private runtime state, or audit history to a portable package.

The validator rejects forbidden authority fields and roots, but it does not secret-scan arbitrary package file contents. Authors must remove secrets placed inside code or content before sharing it. A fork copies code and schema, not state or access.

Immutable change flow

active revision
  -> fork isolated draft
  -> pull, change, diff, and push
  -> validate exact draft version
  -> preview the sealed revision while the active tenant stays unchanged
  -> promote with expected active revision
  -> optionally deploy to explicit targets

Validation does not activate. Failed validation, deployment, or stale promotion leaves the prior active revision unchanged. Rollback activates a prior package through a new audited operation; it does not rewind state.

Next: follow the CLI lifecycle, add package extensions, or review security and isolation.