@runeditrun/rer 0.2.63 → 0.2.65

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/cli/README.md CHANGED
@@ -1,5 +1,18 @@
1
1
  # Portable command sources
2
2
 
3
+ To bring existing data into a seed, sign in as the owner and use its import
4
+ screen. First step: open this path on the destination app:
5
+
6
+ ```text
7
+ /app/import
8
+ ```
9
+
10
+ Upload a supported source export, review the plan and its differences, then
11
+ approve that exact plan to apply it. Reconcile the result against native data;
12
+ use Undo from the same history when needed. Base's reference accepts people JSON
13
+ here, not installation `.rer` archives. Editions adopt this same door
14
+ with their own supported readers and native adapters.
15
+
3
16
  `bin/rer.mjs` dispatches `cli/main.mjs`. Parsing/contract declarations, project
4
17
  resolution, output/exits, shared lifecycle orchestration, local state/reset,
5
18
  transfers, independent argv and diagnostics are separate modules. `dev-identity.mjs`
@@ -32,11 +45,16 @@ names what each mode's command targets are and reads the lockfile entry that
32
45
  that still calls the removed copy, which `check` refuses (SC-13.package.calls). `global/README.md` lists the exports and the vendored
33
46
  path each replaces.
34
47
 
35
- `node scripts/export-reference.mjs NEW_PATH` creates a standalone copy of the
48
+ ## Create a seed from source
49
+
50
+ `exportReference` / `node scripts/export-reference.mjs NEW_PATH` creates a standalone copy of the
36
51
  reference with runtime imports relocated into its own source tree and an explicit
37
52
  transformation inventory. It preserves source/tool pins and the real app; it does
38
53
  not substitute an application fixture. Frozen dependency installation occurs
39
- separately. Refresh copied sources with the export tools after shared edits.
54
+ separately. This is seed creation from source, not an export of an installed
55
+ owner's data. Refresh copied sources with the export tools after shared edits.
56
+
57
+ ## Shared command lifecycle
40
58
 
41
59
  Every first-party seed declares `commandAdapter` alongside its installer hooks.
42
60
  `localInstaller.run` supplies shared setup lifecycle behavior; the RER command
@@ -66,6 +84,12 @@ For older installations without an answer record, a runtime selection outside
66
84
  the installer field's choices cannot replace an adapter-declared local choice.
67
85
  Explicit answers and recorded installer choices still undergo strict validation.
68
86
 
87
+ ## Back up and restore this installation
88
+
89
+ Use `rer export` / `rer import` to back up and restore this installation. This
90
+ is separate from bringing records in through the reviewed import door. Archive
91
+ restore has no door plan, reviewed fingerprint, reconciliation or Undo. Keep owner move-in instructions at `/app/import`.
92
+
69
93
  Local `export --output FILE` and `import --input FILE --yes` use the Base
70
94
  portability implementation through the shared command runner and real Wrangler
71
95
  bindings. Seed adapters declare their database, buckets and archive policy.
@@ -1,5 +1,18 @@
1
1
  # Shipped vendor exports
2
2
 
3
+ To bring existing data into a seed, sign in as the owner and use its import
4
+ screen. First step: open this path on the destination app:
5
+
6
+ ```text
7
+ /app/import
8
+ ```
9
+
10
+ Upload a supported source export, review the plan and its differences, then
11
+ approve that exact plan to apply it. Reconcile the result against native data;
12
+ use Undo from the same history when needed. Base's reference accepts people JSON
13
+ here, not installation `.rer` archives. Editions adopt this same door
14
+ with their own supported readers and native adapters.
15
+
3
16
  `exportVendor(vendor, {key, inputs, checkpoint, signal})` is an async generator.
4
17
  It yields `{name, bytes: Buffer, checkpoint}`. Keys remain in memory and are
5
18
  attached only to GET requests on the adapter's fixed HTTPS origin. Redirects,
package/cli/contract.mjs CHANGED
@@ -12,8 +12,8 @@ const definitions = {
12
12
  verify: [[], 'Run the complete internal verification target.'],
13
13
  reset: [['--yes'], 'Confirmed removal of the declared local inventory only.'],
14
14
  deploy: [['--owner-name', '--environment', '--dry-run', '--site', '--demo', '--host', '--env-file', '--image', '--bind-address', '--http-port', '--https-port', '--remove', '--yes', '--set-secret', '--unset-secret', '--rotate-secret'], 'Owner-account deployment and health; dry run validates/builds locally and reads target secret bindings with Cloudflare credentials, without provider writes. Missing required secrets fail as in deploy; missing credentials or unreadable target secrets also fail. Builds and deploy hooks run with the checkout\'s local settings files moved aside, and a build output holding one (.dev.vars, .env) is refused. Declared secrets come from the environment or --env-file (an owned 0600 KEY=VALUE file); a new Worker gets the local setup owner and fresh generated secrets when they are not given. rer keeps the secrets it generates in .rer/deploy/ENVIRONMENT.secrets.env (0600) and reuses them on every redeploy; it refuses to generate a replacement for one a live Worker holds, and --rotate-secret NAME[,NAME] replaces them on purpose. After a healthy deploy rer claims the setup owner on the hosted app with the saved setup owner name and the one-time setup token, then removes the token. If the installer declares an owner-name field and no name is saved, deploy asks once and saves it; --non-interactive requires --owner-name NAME before any upload. --set-secret NAME[,NAME] (each value from the environment or --env-file; repeat the flag or join names with commas) and --unset-secret NAME[,NAME] change those secrets of the deployed Worker without a build, all of them in one new Worker version or none, and record that version; a missing value refuses before any change. --remove --yes deletes what this environment\'s deploy record says rer created (Worker, D1, R2, KV, queues), reads back that each is gone, and touches nothing else. --site deploys the run site instead: an assets-only Worker on its custom domain with www redirected; with --dry-run it builds the site and prints the plan with no provider request. --demo deploys the hosted demo instead (deploy-demo.json): a front Worker on demo.<domain> giving each visitor their own signed-in, throwaway native Worker isolate of this seed with real public reads/checks and simulated external writes; --dry-run writes it to .rer/demo-host with no provider request; --demo --remove --yes deletes that demo (its Worker, demo.<domain> Custom Domain, each only while the record its deploy left proves it the demo\'s), reads back that each is gone, and is a no-op once it is.'],
15
- export: [['--target', '--output', '--origin', '--session-file'], 'Complete supported archive of the local copy on this computer, with integrity and exclusions, written to --output. The hosted install cannot be exported yet: --origin or --target remote refuses (exit 2) before any effect and names the command that saves the hosted database.'],
16
- import: [['--target', '--input', '--journal', '--origin', '--session-file', '--yes', '--legacy-v1', '--acknowledge-unverified-metadata', '--output'], 'Confirmed atomic restore into an empty destination; --journal LATER_ARCHIVE also fences rows that installation erased since. Backup-only local v1 recovery requires --legacy-v1 --acknowledge-unverified-metadata and a new --output v2 archive; --journal requires normal v2 import.'],
15
+ export: [['--target', '--output', '--origin', '--session-file'], 'For owner move-in, run rer dev and open /app/import: export people there, then upload through the destination door. Developer-only installation backup: complete supported archive of the local copy on this computer, with integrity and exclusions, written to --output. The hosted install cannot be exported yet: --origin or --target remote refuses (exit 2) before any effect and names the command that saves the hosted database.'],
16
+ import: [['--target', '--input', '--journal', '--origin', '--session-file', '--yes', '--legacy-v1', '--acknowledge-unverified-metadata', '--output'], 'For owner move-in, run rer dev and open /app/import: upload, review and apply through the door. Developer-only installation recovery: confirmed atomic restore into an empty destination; --journal LATER_ARCHIVE also fences rows that installation erased since. Backup-only local v1 recovery requires --legacy-v1 --acknowledge-unverified-metadata and a new --output v2 archive; --journal requires normal v2 import.'],
17
17
  doctor: [[], 'Read-only installed tool, configuration and state diagnostics.'],
18
18
  describe: [[], 'Read-only description of actual command capabilities.'],
19
19
  check: [['--profile'], 'Read-only structural command contract and operations validation.'],
package/cli/parse.mjs CHANGED
@@ -106,7 +106,8 @@ export function parse(argv, cwd = process.cwd(), { independent = false, deferTai
106
106
  export function help(verb) {
107
107
  if (!verb) return `Usage: rer VERB [FLAGS]\nCommands: ${Object.keys(verbs).join(', ')}, signin, release\nRun rer VERB --help for flags.\n`;
108
108
  const known = verbs[verb] ?? (verb === 'signin' ? signinVerb : undefined);
109
- return `Usage: rer ${verb} [FLAGS]\nFlags: ${(known?.flags ?? commonFlags).join(', ')}\n${known?.effects ?? 'Execute the declared OPERATIONS v2 argv with explicit arguments after --.'}\n`;
109
+ const door = ['export', 'import'].includes(verb) ? 'To move records, start the app and open its signed-in owner import door:\n\n rer dev\n\nOpen /app/import, then export or upload and review supported records there.\n\nTo back up or restore this installation:\n' : '';
110
+ return `${door}Usage: rer ${verb} [FLAGS]\nFlags: ${(known?.flags ?? commonFlags).join(', ')}\n${known?.effects ?? 'Execute the declared OPERATIONS v2 argv with explicit arguments after --.'}\n`;
110
111
  }
111
112
 
112
113
  function distance(a,b){let row=Array.from({length:b.length+1},(_,i)=>i);for(let i=1;i<=a.length;i++){const next=[i];for(let j=1;j<=b.length;j++)next[j]=Math.min(next[j-1]+1,row[j]+1,row[j-1]+(a[i-1]===b[j-1]?0:1));row=next;}return row[b.length];}
package/cli/release.mjs CHANGED
@@ -14,7 +14,7 @@ Without --tag, write a preview. This command never pushes, uploads or deploys.
14
14
  --ref REF Selected committed source (default: HEAD).
15
15
  --public-base REF Public history as GIT_URL#BRANCH for exact-source scans;
16
16
  defaults to this public repository's default branch.
17
- --tag [vVERSION] Prepare source artifacts and create a local annotated tag;
17
+ --tag [vVERSION] Prepare source artifacts and create or adopt an annotated tag;
18
18
  an explicit tag must match the committed release version.
19
19
  --dry-run Run the real gates and suppress local tag creation.
20
20
  --local-verify Run the seed's full verification locally instead of
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.65
4
+
5
+ - **Tag-first patch releases (#302).** rer release --tag adopts an existing remote annotated version tag at the exact source commit after its tag Verify passes. The producer captures one immutable tag object and checks object/commit equality before mutation and RELEASED. The existing release-tag Verify rule remains in force.
6
+ - **Current contract validation for every release (#302).** Contract inheritance is disabled. Patch lines must update older contracts to the current format before releasing; local predecessor tags cannot manufacture a passing judgment.
7
+ - **Business import authority (#293).** Seeds can enable their import door at first owner claim and heal an interrupted enable on later owner paths, while preserving an owner's later disablement and key revocations. verifyRerGrant validates exact RER-signed read grants outside the import door.
8
+
9
+ ## 0.2.64
10
+
11
+ - **Records start at one import door (#296).** The default seed uses upload, review, apply, reconcile and undo; the legacy importer is removed. Records export/import docs, templates and CLI help start at the door. Installation archives remain a separate backup/restore path. Adopting seeds follow [ADOPTING.md](../modules/import-kit/src/door/ADOPTING.md).
12
+ - **Documented shared-door limits remain.** Erasing a completed head blocks later plans in that lineage. Retired email-labelled jobs return `409 plan_custody_mismatch` on status/undo.
13
+ - **Readable contract progress (#301).** The shared /contract stat block and clause table wrap without overlap from 360 to 2560 pixels.
14
+
3
15
  ## 0.2.63
4
16
 
5
17
  - **Business connect waits for approval and keeps durable state (#277).** Pairing resumes after interruption, sends a readable device name and working folder, and accepts an explicit `RER_BUSINESS_STATE_DIR` when the usual state folder is unwritable. A refused macOS Keychain write stops before redeeming the code and explains how to approve the command outside the sandbox. Browser choices remain authoritative.
@@ -1,5 +1,18 @@
1
1
  # Portable container hosting
2
2
 
3
+ To bring existing data into a seed, sign in as the owner and use its import
4
+ screen. First step: open this path on the destination app:
5
+
6
+ ```text
7
+ /app/import
8
+ ```
9
+
10
+ Upload a supported source export, review the plan and its differences, then
11
+ approve that exact plan to apply it. Reconcile the result against native data;
12
+ use Undo from the same history when needed. Base's reference accepts people JSON
13
+ here, not installation `.rer` archives. Editions adopt this same door
14
+ with their own supported readers and native adapters.
15
+
3
16
  An image contains the seed's real Vite server/client build, migrations and the
4
17
  shared host. Workers remains the default. Opt in with `platforms` in `deploy.json`:
5
18
 
@@ -98,7 +111,8 @@ supervises the process; an unexpected runner exit stops the host so Compose can
98
111
  restart the complete unit. The runner owns its transport's public-address
99
112
  validation and TLS behavior.
100
113
 
101
- Local container export/import uses the same Base archive service and exclusion
114
+ To back up and restore this installation in a local container, use the same
115
+ Base archive service and exclusion
102
116
  policy as Workers. Stop the serving process first: one-shot transfers acquire
103
117
  the same volume lock. `rer archive diff BEFORE AFTER` verifies both entire
104
118
  archives, then reports added/removed/changed row keys, objects and payloads.
@@ -1,5 +1,18 @@
1
1
  # Application dependency links
2
2
 
3
+ To bring existing data into a seed, sign in as the owner and use its import
4
+ screen. First step: open this path on the destination app:
5
+
6
+ ```text
7
+ /app/import
8
+ ```
9
+
10
+ Upload a supported source export, review the plan and its differences, then
11
+ approve that exact plan to apply it. Reconcile the result against native data;
12
+ use Undo from the same history when needed. Base's reference accepts people JSON
13
+ here, not installation `.rer` archives. Editions adopt this same door
14
+ with their own supported readers and native adapters.
15
+
3
16
  This module implements the application side of the pull-link protocol. Auth's
4
17
  provider implementation (auth-7) is separate. `createDependencies` mounts the
5
18
  well-known routes and owner controls; `AuthConfig.dependencies: true` resolves
@@ -180,7 +193,9 @@ refused. Credential consumers must record/check the fence; the provided
180
193
  with no recorded fence. Editor grants require the actual current install owner;
181
194
  OIDC sessions must also match that owner's current issuer/subject account binding.
182
195
 
183
- Exports omit server link keys, approvals, code state, provider sessions and OIDC
196
+ To back up and restore this installation, apply the following identity policy
197
+ to its archives. This is separate from bringing records in through the door.
198
+ Archives omit server link keys, approvals, code state, provider sessions and OIDC
184
199
  transients, preserve durable people/bindings/grant use/sector, set sign-in off and
185
200
  mark links as needing re-link. Import checks these conditions and requires an
186
201
  explicit fresh provider approval. Local `rer import` returns `needsRelink: true`
@@ -1,5 +1,18 @@
1
1
  # Subject erasure
2
2
 
3
+ To bring existing data into a seed, sign in as the owner and use its import
4
+ screen. First step: open this path on the destination app:
5
+
6
+ ```text
7
+ /app/import
8
+ ```
9
+
10
+ Upload a supported source export, review the plan and its differences, then
11
+ approve that exact plan to apply it. Reconcile the result against native data;
12
+ use Undo from the same history when needed. Base's reference accepts people JSON
13
+ here, not installation `.rer` archives. Editions adopt this same door
14
+ with their own supported readers and native adapters.
15
+
3
16
  This dependency-free source module erases one subject (a person, contact,
4
17
  requester, booking and so on) and everything a seed declares as depending on
5
18
  it, for BASE-DATA-003. Audit records survive with an anonymised reference
@@ -163,7 +176,8 @@ the seed retires them in its own migration.
163
176
  only the subject), so an older archive that contains any of those rows is
164
177
  refused on restore. The fence's own limit stays: an old archive offered to a
165
178
  brand-new store that has no journal cannot be recognised. Supply the owner's
166
- later journal there (`rer import --journal LATER_ARCHIVE`).
179
+ later journal there (restore this installation with
180
+ `rer import --journal LATER_ARCHIVE`, separate from the reviewed import door).
167
181
  - **import-kit.** `nativeStatements(entity, subject)` returns the whole D1 phase
168
182
  as `{sql, params}` statements for `eraseD1ImportTarget(kind, id,
169
183
  nativeStatements, context)`. Kit custody, the product cascade and the fence
@@ -1,5 +1,22 @@
1
1
  # Portable installation data
2
2
 
3
+ To bring existing data into a seed, sign in as the owner and use its import
4
+ screen. First step: open this path on the destination app:
5
+
6
+ ```text
7
+ /app/import
8
+ ```
9
+
10
+ Upload a supported source export, review the plan and its differences, then
11
+ approve that exact plan to apply it. Reconcile the result against native data;
12
+ use Undo from the same history when needed. Base's reference accepts people JSON
13
+ here, not installation `.rer` archives. Editions adopt this same door
14
+ with their own supported readers and native adapters.
15
+
16
+ Use this module to back up and restore this installation, separately from
17
+ bringing records in through the reviewed import door. Its restore has no door
18
+ plan or Undo, and the door does not accept its `.rer` archives.
19
+
3
20
  This dependency-free source module exports and restores one installation's D1
4
21
  tables, R2 objects and optional named byte payloads. It is generalised from the
5
22
  Penny and Orbit seeds, with atomic graph restoration from Lamp. Products retain
@@ -115,12 +115,63 @@ registry is input for that integration, not a replacement for the site's registr
115
115
 
116
116
  By default, success writes only the receipt, publication report and site preview;
117
117
  its provenance says `publication: dry-run`. It creates no tag or source archive.
118
- Pass **`--tag`** to create an annotated local `v<version>` tag at the verified
119
- commit and the exact source export. Existing tags are never changed. The command
118
+ Pass **`--tag`** or **`--tag v<version>`** to prepare the exact source export
119
+ and an annotated local version tag at the verified commit, or adopt the matching
120
+ remote annotated tag described below. Existing tags are never changed. The command
120
121
  **never pushes,
121
122
  changes repository visibility, dispatches Actions, deploys or edits a site**.
122
123
  Publication and deployment retain their separate owner authorization.
123
124
 
125
+ ### Tag-first patch release
126
+
127
+ For an ordinary release from an already public source repository, push the
128
+ release branch, then push the annotated version tag before producing artifacts.
129
+ This lets the tag's Verify run authorize that exact commit. In the clean source
130
+ checkout, set the existing publication inputs above and run:
131
+
132
+ ```sh
133
+ set -eu
134
+ source_sha="$(git rev-parse HEAD)"
135
+ tag="$(git show "$source_sha:seed.json" | node --input-type=module -e 'let text=""; for await (const part of process.stdin) text += part; console.log("v" + JSON.parse(text).version)')"
136
+ release_message="$(git show "$source_sha:RELEASE.json" | node --input-type=module -e 'let text=""; for await (const part of process.stdin) text += part; const release=JSON.parse(text), notes=release.publicReleaseNotes; if (notes !== undefined && (typeof notes !== "string" || !notes.trim())) throw Error("Public release notes must be nonempty text"); process.stdout.write(process.argv[1] + (notes ? "\n\n" + notes.trim() : ""))' "$tag")"
137
+ git push origin HEAD
138
+ git -c tag.gpgSign=false tag -a --cleanup=verbatim "$tag" "$source_sha" -m "$release_message"
139
+ git push origin "refs/tags/$tag"
140
+ ```
141
+
142
+ Wait for the selected Verify workflow's tag run to complete successfully on
143
+ `source_sha`. Then, from Base, produce the release using that same source SHA
144
+ and explicit tag (substitute the source checkout and a new output directory):
145
+
146
+ ```sh
147
+ pnpm rer release --repo /path/to/seed --ref "$source_sha" --tag "$tag" \
148
+ --project "$PUBLIC_PROJECT" --repository "$PUBLIC_REPOSITORY" \
149
+ --output /path/to/new-release-directory
150
+ ```
151
+
152
+ The annotation message is exactly the version tag, followed, only when public
153
+ notes are present, by two newlines and the trimmed committed
154
+ `RELEASE.json.publicReleaseNotes`, then exactly one final newline. The producer
155
+ uses verbatim annotation text; do not add a summary or signing footer.
156
+ A remote tag is adopted only when it is an annotated tag directly targeting the
157
+ selected source commit, its embedded tag name and the requested tag both match
158
+ `v<version>`, and its message bytes exactly match the generated annotation. A
159
+ lightweight tag, nested tag, different commit, name or message is refused. The
160
+ receipt records the adopted tag object ID; the producer preserves that object
161
+ instead of recreating it. Before importing a tag and before reporting RELEASED,
162
+ the producer requires the captured tag object and its direct source commit to
163
+ remain identical, including the staged ref used during the build. A changed
164
+ remote, local or staged tag refuses release. This does not relax GitHub Verify selection or any
165
+ publication, installation, build or integrity gate. Parentless and public-child
166
+ exports retain their separate source/export identities described below.
167
+
168
+ Every release uses the current contract parser on the selected commit's
169
+ `CONTRACT.md`, including stable patches with unchanged contract bytes. Existing
170
+ release artifacts do not record an authenticated fresh contract PASS that could
171
+ authorize inheritance. A local or published predecessor tag alone cannot supply
172
+ that judgment. Older contracts must be refreshed to the current format before
173
+ release; the catalogue derives its published clauses from that validated contract.
174
+
124
175
  `--dry-run` performs the selected verification path, local artifact steps and history scan and suppresses
125
176
  tag creation even with `--tag`. `--tag --dry-run` also prepares the source archive
126
177
  for inspection. Existing tags do not prevent previews.
@@ -292,7 +343,7 @@ signing material from the vault through `--key-stdin`; `sign` never echoes it.
292
343
  `--key-stdin` refuses terminal input; pipe the key from a vault or file instead.
293
344
 
294
345
  Signing requires `release-receipt.json` to record a completed `RELEASED`
295
- tagged release with a created public tag. It writes the detached DSSE envelope
346
+ tagged release with a created or adopted public tag. It writes the detached DSSE envelope
296
347
  as `rer-release.dsse.json` beside the receipt. The statement binds the public
297
348
  repository, tag, commit, tree and tag object, and hashes `public-source.tar`,
298
349
  `release-receipt.json`, `publish-check.json`, the bundle's single
@@ -20,7 +20,11 @@ export function catalogue(source, project, repository, gates, dryRun) {
20
20
  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(s.id)) throw Error('Invalid seed listing ID');
21
21
  for (const key of ['name', 'category', 'description', 'maturity'])
22
22
  if (typeof s[key] !== 'string' || !s[key]) throw Error('Incomplete seed listing metadata');
23
- const contract = clauses(source.bytes('CONTRACT.md').toString());
23
+ const contractBytes = source.bytes('CONTRACT.md');
24
+ // Published releases do not record an authenticated fresh contract judgment.
25
+ // Tags and matching bytes alone cannot authorize skipping today's parser.
26
+ const contract = clauses(contractBytes.toString());
27
+ if (!contract.length) throw Error('CONTRACT.md must contain published clauses');
24
28
  const licence = source.bytes('LICENSE').toString();
25
29
  if (!licence.includes('Permission is hereby granted, free of charge')) throw Error('Declare a supported listing license');
26
30
  const docs = ['seed.json', 'CONTRACT.md', 'AGENTS.md', 'LICENSE', 'RELEASE.json',
@@ -28,8 +28,8 @@ export function releaseMessage(source) {
28
28
  }
29
29
 
30
30
  export function annotate(repo, source, commit, name = source.tag) {
31
- git(repo, '-c', 'user.name=Run Edit Run', '-c', 'user.email=releases@runeditrun.invalid', '-c', 'core.hooksPath=/dev/null',
32
- 'tag', '-a', name, commit, '-m', releaseMessage(source));
31
+ git(repo, '-c', 'user.name=Run Edit Run', '-c', 'user.email=releases@runeditrun.invalid', '-c', 'core.hooksPath=/dev/null', '-c', 'tag.gpgSign=false',
32
+ 'tag', '-a', '--cleanup=verbatim', name, commit, '-m', releaseMessage(source) + '\n');
33
33
  }
34
34
 
35
35
  export function cleanHistory(source, temporary, tagged = false) {
@@ -9,6 +9,7 @@ import { publicationScan, sourcePublicationScan, validatePublicationDestination
9
9
  import { publicDestination, requirePublicDestination, remotePublicHead, publicChild, assertPublicTree } from './public-child.mjs';
10
10
  import { writePublishHandoff } from './publish-handoff.mjs';
11
11
  import { releasePublicBase } from './public-base.mjs';
12
+ import { prepareTagAdoption, confirmTagAdoption, assertTagAdoption } from './tag-adoption.mjs';
12
13
  import { placeholderMarks, placeholderMessage } from '../../cli/placeholder-mark.mjs';
13
14
 
14
15
  // Failure output belongs to the private receipt, not the site preview.
@@ -30,7 +31,7 @@ export async function release({ repo, ref = 'HEAD', output, project, repository,
30
31
  releaseMessage(source);
31
32
  if (typeof tag === 'string' && tag !== source.tag) throw Error('Requested tag must match the committed release version');
32
33
  const existing = git(source.repo, 'tag', '--list', source.tag).toString().trim();
33
- if (existing && tag && !dryRun) throw Error('Release tag already exists; choose a new committed version');
34
+ if (existing && tag && !dryRun && (onto !== undefined || clean)) throw Error('Release tag already exists; choose a new committed version');
34
35
  // Validate metadata before installs or output writes.
35
36
  catalogue(source, project, repository, { verify: { status: 'PENDING' }, publishCheck: { status: 'PENDING' } }, preview);
36
37
  const destination = onto !== undefined ? publicDestination(onto, repository, source.repo) : null;
@@ -47,6 +48,7 @@ export async function release({ repo, ref = 'HEAD', output, project, repository,
47
48
  const checkout = resolve(temporary, 'seed');
48
49
  git(source.repo, 'clone', '--no-hardlinks', '--no-checkout', '--', source.repo, checkout);
49
50
  git(checkout, 'checkout', '--detach', source.commit);
51
+ const adopted = tag && !dryRun && !destination && !clean ? prepareTagAdoption(source, checkout) : null;
50
52
  const verify = await verifySource(source, checkout, localVerify, verifyWorkflow);
51
53
  // Explicit clean-history publication scans every byte and ref of the actual
52
54
  // parentless export. Exact-source releases classify against public history
@@ -55,7 +57,7 @@ export async function release({ repo, ref = 'HEAD', output, project, repository,
55
57
  : clean ? cleanHistory(source, temporary, Boolean(tag)) : null;
56
58
  let report = exported
57
59
  ? publicationScan(exported.repo, exported.commit, envFile, project, repository, scanBase)
58
- : sourcePublicationScan(source, temporary, envFile, project, repository, scanBase, Boolean(tag));
60
+ : sourcePublicationScan(source, temporary, envFile, project, repository, scanBase, Boolean(tag), adopted);
59
61
  if (destination) {
60
62
  assertPublicTree(exported.repo, exported.commit, source.tree);
61
63
  if (report.status === 'PASS' && (report.complete !== true || report.guarantees?.historyScanned !== true ||
@@ -97,8 +99,13 @@ export async function release({ repo, ref = 'HEAD', output, project, repository,
97
99
  if (tag && !dryRun) {
98
100
  // Public-child writes every artifact before the last guard/source tag,
99
101
  // so a failed write or changed remote cannot leave a private tag.
100
- if (!destination) annotate(source.repo, source, source.commit);
101
- receipt.tag.created = true;
102
+ if (adopted) {
103
+ confirmTagAdoption(source, adopted);
104
+ Object.assign(receipt.tag, { adopted: true, object: adopted.object });
105
+ } else {
106
+ if (!destination) annotate(source.repo, source, source.commit);
107
+ receipt.tag.created = true;
108
+ }
102
109
  // Bind the receipt to the annotated tag in the published history.
103
110
  // Clean/public-child exports have a different commit from the source.
104
111
  const tagRepo = exported?.repo ?? source.repo, tagRef = `refs/tags/${source.tag}`;
@@ -111,6 +118,12 @@ export async function release({ repo, ref = 'HEAD', output, project, repository,
111
118
  }
112
119
  }
113
120
  if (passed && tag && destination) writePublishHandoff(output, destination, receipt);
121
+ if (passed && adopted) {
122
+ assertTagAdoption(source, adopted, { imported: true });
123
+ if (receipt.tag.object !== adopted.object || receipt.publicExport.tagObject !== adopted.object ||
124
+ receipt.publicExport.commit !== adopted.commit || receipt.source.commit !== adopted.commit)
125
+ throw Error('Adopted release tag identity does not match the release receipt');
126
+ }
114
127
  writeFileSync(resolve(output, 'release-receipt.json'), json(receipt), { flag: 'wx' });
115
128
  if (passed && destination) {
116
129
  requirePublicDestination(destination);
@@ -34,10 +34,13 @@ export function publicationScan(repo, ref, envFile, project, repository, publicB
34
34
  // This is the ordinary release gate, also usable without installing/building a
35
35
  // seed. The scanner sees the original checkout and every source ref; only the
36
36
  // new annotation is read from the clean candidate, never verification output.
37
- export function sourcePublicationScan(source, temporary, envFile, project, repository, publicBase, tagged) {
37
+ export function sourcePublicationScan(source, temporary, envFile, project, repository, publicBase, tagged, adopted) {
38
38
  const started = performance.now();
39
39
  let annotationFile;
40
- if (tagged) {
40
+ if (adopted) {
41
+ annotationFile = resolve(temporary, 'annotation.tag');
42
+ writeFileSync(annotationFile, git(adopted.repo, 'cat-file', 'tag', adopted.object), { mode: 0o600 });
43
+ } else if (tagged) {
41
44
  const candidate = resolve(temporary, 'annotation');
42
45
  git(source.repo, 'clone', '--no-hardlinks', '--no-checkout', '--', source.repo, candidate);
43
46
  git(candidate, 'checkout', '--detach', source.commit);
@@ -26,7 +26,9 @@ export async function signArtifact(options) {
26
26
  if (privateKey.asymmetricKeyType !== 'ed25519') throw new Error();
27
27
  } catch { refuse('SIGNATURE_INVALID'); }
28
28
  const artifact = await readArtifact(options.artifact);
29
- if (artifact.receipt.status !== 'RELEASED' || artifact.receipt.tag?.created !== true) refuse('SUBJECT_MISMATCH');
29
+ const tag = artifact.receipt.tag;
30
+ if (artifact.receipt.status !== 'RELEASED' || !(tag?.created === true ||
31
+ (tag?.adopted === true && tag.object === artifact.subject.tagObject))) refuse('SUBJECT_MISMATCH');
30
32
  const scope = options.scope ?? 'rer', issuedAt = timestamp(new Date());
31
33
  // This ephemeral proof checks our output, not publisher admission. The
32
34
  // consumer still needs a separately reviewed anchor with the real owner ID.
@@ -0,0 +1,100 @@
1
+ import { resolve } from 'node:path';
2
+ import { randomUUID } from 'node:crypto';
3
+ import { publicGit, publicOid } from './public-git.mjs';
4
+ import { githubSource } from './github-verify.mjs';
5
+ import { releaseMessage } from './export.mjs';
6
+
7
+ function remoteObject(repo, url, ref) {
8
+ const rows = publicGit(repo, ['--git-dir=/dev/null', 'ls-remote', '--refs', '--', url, ref])
9
+ .toString().trim().split('\n').filter(Boolean);
10
+ if (!rows.length) return null;
11
+ const [oid, name, extra] = rows[0].split('\t');
12
+ if (rows.length !== 1 || name !== ref || extra !== undefined || !/^[a-f0-9]{40}$/.test(oid))
13
+ throw Error('Remote release tag is ambiguous');
14
+ return oid;
15
+ }
16
+
17
+ function referenceObject(repo, ref) {
18
+ const prefix = `${ref} `;
19
+ const row = publicOid(repo, 'for-each-ref', '--format=%(refname) %(objectname)', ref)
20
+ .split('\n').find(line => line.startsWith(prefix));
21
+ return row ? row.slice(prefix.length) : null;
22
+ }
23
+
24
+ function tagObject(repo, ref, object, commit, reason) {
25
+ if (referenceObject(repo, ref) !== object) throw Error(reason);
26
+ if (publicOid(repo, 'cat-file', '-t', object) !== 'tag')
27
+ throw Error('Existing release tag must be an annotated tag object');
28
+ const raw = publicGit(repo, ['cat-file', 'tag', object]);
29
+ // Check the bytes too: the build has write access to this object store.
30
+ if (publicGit(repo, ['hash-object', '-t', 'tag', '--stdin'], raw).toString().trim() !== object)
31
+ throw Error(reason);
32
+ const split = raw.indexOf('\n\n');
33
+ const headers = raw.subarray(0, split).toString('utf8').split('\n');
34
+ if (split < 0 || headers[0] !== `object ${commit}` || headers[1] !== 'type commit' ||
35
+ publicOid(repo, 'rev-parse', `${ref}^{commit}`) !== commit)
36
+ throw Error('Existing annotated tag must point directly at the exact source commit');
37
+ return { raw, split, headers };
38
+ }
39
+
40
+ // Inspect the published object in isolation. Never retarget a local or remote
41
+ // tag, and never use the presence of a tag as verification evidence.
42
+ export function prepareTagAdoption(source, checkout) {
43
+ const ref = `refs/tags/${source.tag}`;
44
+ const local = referenceObject(source.repo, ref);
45
+ const repository = githubSource(source);
46
+ if (!repository) {
47
+ if (local) throw Error('Release tag already exists; adoption requires its remote GitHub source tag');
48
+ return null;
49
+ }
50
+ const url = `https://github.com/${repository}`;
51
+ const object = remoteObject(source.repo, url, ref);
52
+ if (!object) {
53
+ if (local) throw Error('Release tag already exists locally but is not published at the source repository');
54
+ return null;
55
+ }
56
+ if (local && local !== object)
57
+ throw Error('Local and remote release tag objects differ');
58
+ const stagedRef = 'refs/rer-release/adopted-tag';
59
+ publicGit(checkout, ['fetch', '--quiet', '--no-tags', '--no-recurse-submodules', '--no-write-fetch-head', '--', url, `${ref}:${stagedRef}`]);
60
+ const { raw, split, headers } = tagObject(checkout, stagedRef, object, source.commit, 'Remote release tag changed during inspection');
61
+ if (headers[2] !== `tag ${source.tag}`) throw Error('Existing annotated tag name must match the committed release version');
62
+ if (!raw.subarray(split + 2).equals(Buffer.from(releaseMessage(source) + '\n')))
63
+ throw Error('Existing annotated tag message must exactly match the release message');
64
+ return Object.freeze({ repo: checkout, url, ref, stagedRef, object, commit: source.commit, local });
65
+ }
66
+
67
+ // The captured identity survives arbitrary ref changes by the source build.
68
+ // The producer also calls this after artifact creation, before returning RELEASED.
69
+ export function assertTagAdoption(source, adopted, { imported = false } = {}) {
70
+ if (source.commit !== adopted.commit || `refs/tags/${source.tag}` !== adopted.ref)
71
+ throw Error('Release source changed during tag adoption');
72
+ tagObject(adopted.repo, adopted.stagedRef, adopted.object, adopted.commit, 'Staged release tag changed during release');
73
+ if (remoteObject(source.repo, adopted.url, adopted.ref) !== adopted.object)
74
+ throw Error('Remote release tag changed during release');
75
+ const local = referenceObject(source.repo, adopted.ref);
76
+ if ((local && local !== adopted.object) || ((adopted.local || imported) && !local))
77
+ throw Error('Local release tag changed during release');
78
+ if (local) tagObject(source.repo, adopted.ref, adopted.object, adopted.commit, 'Local release tag changed during release');
79
+ return local;
80
+ }
81
+
82
+ export function confirmTagAdoption(source, adopted) {
83
+ const local = assertTagAdoption(source, adopted);
84
+ if (!local) {
85
+ const importedRef = `refs/rer-release/imported-tag-${randomUUID()}`;
86
+ try {
87
+ // Never fetch a build-controlled ref directly into the source tag.
88
+ publicGit(source.repo, ['fetch', '--quiet', '--no-tags', '--no-recurse-submodules', '--no-write-fetch-head', '--',
89
+ resolve(adopted.repo), `${adopted.object}:${importedRef}`]);
90
+ tagObject(source.repo, importedRef, adopted.object, adopted.commit, 'Imported release tag changed during release');
91
+ assertTagAdoption(source, adopted);
92
+ // The missing-tag snapshot is the expected old value, including when a
93
+ // concurrent writer creates the same object while the import runs.
94
+ publicGit(source.repo, ['update-ref', '--no-deref', adopted.ref, adopted.object, '0'.repeat(40)]);
95
+ } finally {
96
+ publicGit(source.repo, ['update-ref', '--no-deref', '-d', importedRef]);
97
+ }
98
+ }
99
+ assertTagAdoption(source, adopted, { imported: true });
100
+ }
@@ -1,5 +1,18 @@
1
1
  # Shared local setup lifecycle
2
2
 
3
+ To bring existing data into a seed, sign in as the owner and use its import
4
+ screen. First step: open this path on the destination app:
5
+
6
+ ```text
7
+ /app/import
8
+ ```
9
+
10
+ Upload a supported source export, review the plan and its differences, then
11
+ approve that exact plan to apply it. Reconcile the result against native data;
12
+ use Undo from the same history when needed. Base's reference accepts people JSON
13
+ here, not installation `.rer` archives. Editions adopt this same door
14
+ with their own supported readers and native adapters.
15
+
3
16
  First-party seeds expose public operations through the RER dispatcher. From a
4
17
  runnable seed checkout, the supported local sequence begins with
5
18
  `rer install`, `rer setup` and
@@ -195,11 +208,13 @@ exports and deployment receipts.
195
208
 
196
209
  ## Data, deployment and verification
197
210
 
198
- Each first-party adapter declares which resources local export/import supports.
211
+ To back up and restore this installation, use the local archive runner. This
212
+ is separate from bringing records in through the reviewed import door. Each
213
+ first-party adapter declares which resources that archive export/restore supports.
199
214
  Every first-party seed verifies a complete local export/import/export round
200
215
  trip across those resources. Archives are private and integrity-checked;
201
216
  owner/auth, historical development mail, private settings and transient runtime state remain
202
- excluded. Import validates and restores atomically into an empty destination.
217
+ excluded. Archive restore validates and restores atomically into an empty destination.
203
218
  Remote transfer is supported only when every required resource has a complete
204
219
  adapter implementation; unsupported targets fail visibly.
205
220
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runeditrun/rer",
3
- "version": "0.2.63",
3
+ "version": "0.2.65",
4
4
  "description": "The rer command: install, set up, run and launch Run Edit Run checkouts.",
5
5
  "license": "MIT",
6
6
  "type": "module",