Package and instance

ARC treats a package and an instance as different objects. Confusing them blurs source ownership, configuration, data, and release.

Package versus instance

	Package	Instance
What it is	Versioned, reusable application artifact	One configured run or deployment of a package
Typical identity	`id` / `did` / `version` in `blocklet.yaml`	Runtime binding: port, host, owner, data mounts
Mutability	Source + published tree at a version	Config and data can change while the package version stays fixed
Local evidence	Directory with `blocklet.yaml` (or convention entry), `arc blocklet inspect`	`arc blocklet run` / `arc service start --blocklet` serving URLs
Build product	`dist/` + `.afs/manifest.json` + `blocklet.dist.json`	Not produced by `build` alone — requires a serve or deploy step
Analogy	npm package / container image	Running container / deployed service

Code-backed anchors (ArcBlock/arc, package types and CLI):

Package shape: blocklet.yaml parsed as BlockletManifest (packages/core/src/blocklet/types.ts)
Scaffold writes package identity (specVersion, id, name, did, version) via arc blocklet create
Local instance serve: arc blocklet run <path> registers the parent directory with the daemon and prints access URLs
Build stamps instance requirements into the flat manifest (e.g. instance.required: false for a basic package; minimal-app build reports instance: requires /instance DID Space)

Stage	Object	Typical command
Author source	Package source tree	editor + `create`
Validate / package	Package contract + `dist/`	`check`, `build`, `inspect`
Local run	Local instance	`blocklet run` / `service start --blocklet`
Remote path	Remote instance	`deploy --server` / Pages — separate, often experimental

Flow from source through package check and build to a local or remote instance

A package is the versioned application unit. An instance is a particular run or deployment of that package.

Concern	Lives on the package	Lives on the instance
`blocklet.yaml` identity, `scope`, mounts, sites, replicated declarations	Yes	No (read as declared by the package)
Built file tree under `dist/`	Yes (artifact)	Consumed when deployed
Daemon port, extra blocklet dirs	No	Yes
`/instance` DID Space data (when required)	Seed only (`seed/`)	Runtime data ownership
Domain binding for a public deployment	Declared candidates (`sites.domains`)	Actual binding for this deployment

From the current parser (BlockletManifest):

Field	Package meaning	Instance implication
`id`, `did`, `version`, `specVersion`	Package identity	Stable package coordinates for a run
`scope`	Namespace visibility model (`app` default, also `user` / `root` / `agent`)	Session AFS shape for the run
`instance.required` / `instance.mount` / `instance.seed`	Declares whether a real `/instance` DID Space is required	Runtime must fail closed if required and missing
`mounts`	Provider dependencies declared by the package	Mounted into the running AFS
`sites` / `surfaces`	Declared routing and exposure	Resolved by the host that serves the instance
`replicated`	Collection contracts in the package	Writes and copies at instance/user spaces

Minimal package written by arc blocklet create --recipe basic (verified):

specVersion: 2
id: demo-basic
name: demo-basic
did: did:blocklet:demo-basic
version: 0.1.0
description: ""

After arc blocklet build, the flat manifest for that package included:

{
  "specVersion": 2,
  "id": "demo-basic",
  "instance": { "required": false, "mount": "/instance" },
  "scope": "app",
  "mounts": []
}

A local instance is enough for acceptance:

arc blocklet run ./demo-min
# or
arc service start --blocklet ./demo-min --port 4939

Verified (2.0.0-beta.28; seed-instance port override, today prefer a named instance):

Serving blocklet "demo-min" on port 4941
  http://demo-min.localhost:4941/
  http://localhost:4941/?blocklet=demo-min  (Safari / universal)

GET with Host: demo-min.localhost:4941 returned HTTP 200. No DID Space publish was required.

Source edits change the package. Rebuild and re-check when you change declared files.
Runtime state belongs to the instance environment (daemon config, ports, DID Space data). Do not treat a successful local serve as proof that a remote instance is healthy.
instance: requires /instance DID Space on a build means stateful features of that package need a real instance space. Local HTTP 200 on a shell page does not prove those writes work — see Publish and deploy and Data and AFS.