excuse-ops 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ExcuseOps contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,214 @@
-# Temporary Holding Version
+# ExcuseOps
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Local-first version control for your personal mythology.**
+
+ExcuseOps is a terminal app for checking whether accounts of a day can coexist. Record who was told what, find timing and travel contradictions, preview a permitted repair, and replay the original history. A thin npm launcher runs the real Python/Z3 engine; SQLite keeps the data on your machine.
+
+This is a fictional-scenario consistency tool, not a truth detector. Results depend on the times, routes and rules you enter. It does not send messages or verify real-world events.
+
+## What it does
+
+- Checks each audience's story and the combined schedule, including uncertainty windows, travel, shared events, ordering and explicitly allowed overlaps.
+- Explains clashes with source statements, travel gaps, a text Lie Meter and a template snitch question. Nothing is actually sent.
+- Separates logical consistency from communication exposure: disconnected audiences do not make contradictory accounts consistent.
+- Suggests bounded start-time translations, minimizing changed statements before total minutes moved. Applying a repair is explicit.
+- Locks versions marked sent. Corrections and retractions preserve the originals rather than rewriting history.
+- Stores revisions and reports locally, with read-only replay and first-break analysis.
+
+There is no browser, web server, cloud account or JavaScript solver fallback.
+
+## Current release and requirements
+
+Version **0.1.0** is the initial early-access CLI release. Registry releases use the **`next`** tag rather than `latest`; installation support is intentionally narrow.
+
+This release is limited to the measured environment below. The launcher enforces the Node version, OS family and CPU architecture; setup enforces the CPython version. Other combinations are not verified or supported:
+
+| Component | Supported combination |
+| --- | --- |
+| Platform | macOS on Apple Silicon; verified on macOS 26.5.1 arm64 |
+| Node.js | 26.7.0 |
+| Python | Existing CPython 3.14.6 |
+| npm | Verified with 11.19.0 |
+| Solver | `z3-solver` 4.16.0.0, installed by explicit setup |
+
+Python is **not** downloaded for you. Set `EXCUSE_OPS_PYTHON` to its executable path if automatic discovery cannot find the supported interpreter.
+
+## Installation
+
+### Install the current local artifact
+
+Obtain `excuse-ops-0.1.0.tgz` from a local build, then install it into a directory you control:
+
+```sh
+mkdir excuseops-demo
+cd excuseops-demo
+npm install --ignore-scripts /absolute/path/to/excuse-ops-0.1.0.tgz
+npx --no-install excuse setup
+npx --no-install excuse --help
+```
+
+`setup` explains the dependency download and asks for consent. It creates a release-specific isolated Python environment and installs the bundled application wheel plus the hash-pinned Z3 wheel. It does not modify system Python. Installing the npm package alone does not run setup: there is no postinstall hook or implicit installation on ordinary commands.
+
+Network access is needed for initial dependency setup. Once setup succeeds, scenario commands work offline without remote services or a repository checkout. Repeating setup verifies and reuses a healthy runtime; an update prepares its own runtime without replacing project databases.
+
+### Registry installation (early access)
+
+Install the early-access channel:
+
+```sh
+npm install excuse-ops@next
+npx --no-install excuse setup
+```
+
+Use `next` explicitly; it does not imply a stable `latest` release. If the registry package is not yet available, use the local tarball installation above. No global installation is required.
+
+## Quick start: the Tuesday contradiction
+
+The commands below use `npx --no-install excuse` from the directory where you installed the package. Prompts are interactive; confirmation defaults to **no**.
+
+### 1. Create and configure a project
+
+```sh
+npx --no-install excuse init
+```
+
+Enter a project name, such as `Tuesday`, and choose a blank project. Run `config` once for each item below, review the proposed change, and confirm saving it:
+
+```sh
+npx --no-install excuse config
+```
+
+| Category | Operation | Values to enter |
+| --- | --- | --- |
+| `people` | `add` | `Boss`, then `Friend` in a separate invocation |
+| `places` | `add` | `Clinic`, then `Arcade` in a separate invocation |
+| `activities` | `add` | `Dentist`, then `Gaming` in a separate invocation |
+| `travel` | `set` | `Clinic`, `Arcade`, `25` minutes, `30` kilometers |
+
+Travel is bidirectional. Do not add a people-link yet.
+
+### 2. Record the accounts
+
+```sh
+npx --no-install excuse add "Dentist at Clinic, 10:00-11:00, told Boss"
+npx --no-install excuse mark-sent <dentist-id>
+npx --no-install excuse merge
+npx --no-install excuse add "Gaming at Arcade, 11:05-12:30, told Friend; may move 11:00-12:30"
+npx --no-install excuse status
+npx --no-install excuse diff
+npx --no-install excuse merge
+```
+
+Replace `<dentist-id>` with the actual ID returned by `add`; do not type angle-bracket placeholders into your shell. Confirm `mark-sent` only to record that the account was communicated—this action sends nothing.
+
+Dentist alone is consistent. Adding Gaming leaves a five-minute gap for a 25-minute trip: the combined merge is **blocked**, even though each audience's story is individually consistent. The entered distance implies 360 km/h over that gap. Without a communication path, exposure is **safe-for-now**, not logically consistent. A blocked merge deliberately returns exit **1** and saves its report; do not use a success-only `&&` chain for the whole example.
+
+### 3. Inspect exposure, preview and apply a repair
+
+```sh
+npx --no-install excuse link Boss Friend --label "group chat"
+npx --no-install excuse merge
+npx --no-install excuse resolve
+npx --no-install excuse resolve --apply <plan-id>
+npx --no-install excuse merge
+npx --no-install excuse log
+npx --no-install excuse log --at <action-id>
+```
+
+Use the plan ID printed by `resolve` and an action ID shown by `log`. Linking changes exposure to **danger** without fixing the clash. The optimal permitted repair moves Gaming by +20 minutes to **11:25–12:50**, preserving its 85-minute duration and the sent Dentist version.
+
+A preview does not change account content or the domain revision. Applying a current plan appends new versions; stale or already-consumed plans are rejected. Replay is read-only: viewing an older blocked/disconnected state does not replace today's repaired workspace.
+
+## Statement syntax
+
+Entities must be configured first. Input is a small, explicit language—not arbitrary natural-language interpretation.
+
+```text
+Dentist at Clinic, 10:00-11:00, told Boss
+Gaming at Arcade, 11:05-12:30, told Friend; may move 11:00-12:30
+Groceries at Market, 45 min, starts 09:00-09:30, told Parent
+Lunch at Cafe, 12:00-13:00, told Boss; event team-lunch; after s1
+```
+
+The last two examples require their own configured names; `s1` must be an actual active statement ID. Start windows express uncertainty, while `may move` bounds permitted replacement starts. Repairs preserve window width, duration, activity, place, audience, shared-event identity and ordering references.
+
+Times use one day at integer-minute resolution. Intervals are half-open; `24:00` is allowed only as an exclusive end. No overnight or multiple-date scheduling. Configured names cannot contain commas, semicolons, newlines, ` at ` or ` told `.
+
+## Commands
+
+Prefix these commands with `npx --no-install excuse`, or use `excuse` directly when its installed bin directory is on your PATH.
+
+| Command | Purpose |
+| --- | --- |
+| `setup` | Explicitly prepare or verify the isolated runtime |
+| `init` | Create a blank or guided project without overwriting an existing one |
+| `config` | Inspect/edit entities, travel, communication links and overlap permissions |
+| `add "<statement>"` | Save an immutable draft version |
+| `edit <id>` | Replace an active draft with a new version |
+| `status`, `diff` | Inspect current accounts, pending changes and report staleness |
+| `merge` | Check stories/global consistency, save a report and explain clashes |
+| `link <person> <person> --label "<label>"` | Record a communication connection; send nothing |
+| `resolve` | Preview permitted repairs without applying them |
+| `resolve --apply <plan-id>` | Revalidate and atomically apply a current plan |
+| `mark-sent <id>` | Confirm a communicated version's lock |
+| `correct <id>`, `retract <id>` | Explicitly supersede or deactivate an account while retaining history |
+| `log`, `log --at <action-id>` | Inspect history or replay an original snapshot read-only |
+| `--help`, `--version` | Show usage or the installed application version |
+
+`merge`, `resolve` and `log` accept `--budget-seconds`. A timeout is unknown/incomplete, never proof of consistency or impossibility. Incomplete repairs are labeled best-found rather than optimal.
+
+## Data, safety and exit codes
+
+Projects live in **`.excuseops/project.sqlite`** beneath the directory where you run `init`. Commands find the nearest initialized ancestor, so child directories use the same project. Back up this database to retain the scenario and its history; runtimes are separate and are not a backup of project data.
+
+Managed runtimes live under **`~/Library/Application Support/ExcuseOps`**, overridden by `EXCUSE_OPS_HOME`. Never delete an unfamiliar runtime directory or setup lock as an automatic recovery step. See the detailed guide for ownership/retry behavior.
+
+| Exit | Meaning |
+| --- | --- |
+| `0` | Successful command/cancellation, consistent merge or completed valid repair search |
+| `1` | Proven contradiction or proven absence of a permitted repair |
+| `2` | Invalid input/usage, missing project/prerequisite or unsupported runtime |
+| `3` | Unknown/timed-out/incomplete solving, including a validated incomplete candidate |
+| `4` | Storage/runtime failure or rejected stale/concurrent mutation |
+| `130` | User interruption |
+
+Sent versions cannot be moved by ordinary edits or repairs. Explicit corrections/retractions retain originals. No command delivers a message, reads live maps or synchronizes a cloud account.
+
+## Verification and known limits
+
+The CLI is checked with real Z3 regressions, a separately authored specification-only AI exhaustive oracle, seeded comparisons and installation of the actual npm tarball outside the checkout. The independent oracle is bounded; its results are not extrapolated to exhaustive 30-account proofs.
+
+Recorded verification includes 138 Python tests, 157 oracle cases, 100 seeded agreements, seven Node launcher tests and an installed-consumer acceptance run covering lifecycle, repair, replay, interruption, quoting, rollback, concurrent writers and upgrades.
+
+Performance is a measured limitation, not a blanket guarantee: at a one-second budget, 14 of 100 measured 30-account repair searches returned valid best-found candidates without completing optimality proofs. The detailed guide records timings, workload scope and provenance.
+
+## Build and development
+
+From a checkout with the already-installed pinned development tools (setuptools 80.9.0, pytest 9.0.2 and z3-solver 4.16.0.0):
+
+```sh
+PYTHONPATH=src .venv/bin/python -m pytest tests -q
+.venv/bin/python scripts/build_npm.py
+npm pack ./npm
+```
+
+The builder copies this root README into the npm payload; do not maintain a second handwritten package README. The tarball bundles the application wheel, launcher, explicit bootstrap and dependency lock—not a prebuilt environment or project data.
+
+To repeat the disposable installed-artifact checks, including setup downloads and a real upgrade, only in an environment where these installations are authorized:
+
+```sh
+.venv/bin/python scripts/verify_artifact.py --allow-install
+```
+
+## Documentation
+
+- [Full CLI guide, grammar, setup and measured limitations](https://github.com/danilocasim/excuse-ops/blob/main/docs/CLI_MVP.md)
+- [Independent checker provenance and supported bounds](https://github.com/danilocasim/excuse-ops/blob/main/verification/ORACLE_PROVENANCE.md)
+- [Implementation and acceptance evidence](https://github.com/danilocasim/excuse-ops/blob/main/.plan/excuse-mvp/TODO.md)
+- [Broader CLI/web product plan](https://github.com/danilocasim/excuse-ops/blob/main/docs/CLI_WEB_IMPLEMENTATION_PLAN.md)
+
+This package delivers the CLI-only milestone. A web UI, multiple dates, actual messaging, cloud collaboration and AI interpretation of arbitrary prose are outside this release.
+
+## License
+
+MIT. See [LICENSE](https://github.com/danilocasim/excuse-ops/blob/main/LICENSE). The bundled application is MIT-licensed; separately installed dependencies retain their own licenses.

package/bin/excuse.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from 'node:child_process';
+import { readFileSync, statSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, delimiter } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+class PrerequisiteError extends Error {}
+
+function exists(path) {
+  try { statSync(path); return true; }
+  catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false;
+    throw error;
+  }
+}
+
+function findPython(release) {
+  const override = process.env.EXCUSE_OPS_PYTHON;
+  const candidates = override ? [resolve(override)] :
+    ['python3.14', 'python3', 'python'].flatMap(name =>
+      (process.env.PATH ?? '').split(delimiter).filter(Boolean).map(directory => join(directory, name)));
+  for (const candidate of [...new Set(candidates)]) {
+    const probe = spawnSync(candidate, ['-I', '-c',
+      'import json,sys; print(json.dumps({"version":list(sys.version_info[:3]),"implementation":sys.implementation.name,"executable":sys.executable}))'],
+    { encoding:'utf8', timeout:5000, shell:false });
+    if (probe.error) {
+      if (probe.error.code === 'ENOENT' || probe.error.code === 'ENOTDIR') continue;
+      throw probe.error; // Permission failures must never trigger another route.
+    }
+    if (probe.status !== 0) continue;
+    let info;
+    try { info = JSON.parse(probe.stdout); } catch { continue; }
+    if (info.implementation === 'cpython' && isDeepStrictEqual(info.version, release.python)) return info.executable;
+  }
+  throw new PrerequisiteError(`CPython ${release.python.join('.')} is required. Install it yourself, or set EXCUSE_OPS_PYTHON to its executable path; Python is never downloaded.`);
+}
+
+function run(command, args) {
+  return new Promise(resolveExit => {
+    // One isolated POSIX process group owns Python and its setup descendants.
+    // The terminal signals Node's group; Node forwards once to this other group.
+    const child = spawn(command, args, { stdio:'inherit', shell:false, detached:true });
+    let signalled = null;
+    let failed = false;
+    function forward(signal) {
+      if (signalled || !child.pid) return;
+      signalled = signal;
+      try { process.kill(-child.pid, signal); }
+      catch (error) { if (error.code !== 'ESRCH') console.error(`Cannot signal runtime: ${error.message}`); }
+    }
+    const interrupt = () => forward('SIGINT');
+    const terminate = () => forward('SIGTERM');
+    process.on('SIGINT', interrupt);
+    process.on('SIGTERM', terminate);
+    child.on('error', error => { failed = true; console.error(`Cannot launch runtime: ${error.message}`); });
+    child.on('close', (code, signal) => {
+      process.off('SIGINT', interrupt);
+      process.off('SIGTERM', terminate);
+      resolveExit(failed ? 4 : signalled === 'SIGINT' || signal === 'SIGINT' ? 130 :
+        signalled === 'SIGTERM' || signal === 'SIGTERM' ? 143 : code ?? 4);
+    });
+  });
+}
+
+async function main() {
+  const release = JSON.parse(readFileSync(join(root, 'release.json'), 'utf8'));
+  if (process.platform !== release.platform || process.arch !== release.arch || process.versions.node !== release.node) {
+    throw new PrerequisiteError(`This artifact is verified only for ${release.platform}/${release.arch}, Node ${release.node}.`);
+  }
+  const args = process.argv.slice(2);
+  if (args[0] === 'setup') {
+    return run(findPython(release), ['-I', join(root, 'bootstrap.py'), '--package-root', root, ...args.slice(1)]);
+  }
+  const override = process.env.EXCUSE_OPS_HOME;
+  const expanded = override === '~' ? homedir() :
+    override?.startsWith('~/') ? join(homedir(), override.slice(2)) : override;
+  const homePath = expanded ? resolve(expanded) : join(homedir(), 'Library', 'Application Support', 'ExcuseOps');
+  const home = exists(homePath) ? realpathSync(homePath) : homePath;
+  const runtime = join(home, 'runtimes', release.runtime_tag);
+  const lock = join(home, 'runtimes', `.${release.runtime_tag}.setup.lock`);
+  const marker = join(runtime, 'ready.json');
+  const python = join(runtime, 'bin', 'python');
+  if (exists(lock) || !exists(marker) || !exists(python)) {
+    throw new PrerequisiteError('No ready runtime for this release. Run excuse setup explicitly.');
+  }
+  let ready;
+  try { ready = JSON.parse(readFileSync(marker, 'utf8')); }
+  catch (error) {
+    if (error.code === 'EACCES' || error.code === 'EPERM') throw error;
+    throw new PrerequisiteError('Runtime readiness metadata is invalid. Run excuse setup to repair it.');
+  }
+  const expected = Object.fromEntries(['version','runtime_tag','files','python','platform','arch'].map(key => [key,release[key]]));
+  if (!isDeepStrictEqual(ready, expected) || realpathSync(runtime) !== resolve(runtime)) {
+    throw new PrerequisiteError('Runtime identity does not match this release. Run excuse setup.');
+  }
+  return run(python, ['-I', '-m', 'excuse_ops', ...args]);
+}
+
+try { process.exitCode = await main(); }
+catch (error) {
+  console.error(error.message);
+  process.exitCode = error instanceof PrerequisiteError ? 2 : 4;
+}

package/bootstrap.py

@@ -0,0 +1,184 @@
+"""Explicit, stdlib-only installation of an npm release's isolated runtime."""
+import argparse
+from contextlib import contextmanager
+import hashlib
+import json
+import os
+from pathlib import Path
+import platform
+import subprocess
+import sys
+from typing import Iterator, Sequence
+import venv
+
+
+class SetupError(RuntimeError):
+    pass
+
+
+class PrerequisiteError(SetupError):
+    pass
+
+
+def digest(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def release(package: Path) -> dict:
+    try:
+        data = json.loads((package / 'release.json').read_text())
+        if data['schema'] != 1:
+            raise PrerequisiteError('Unsupported release manifest.')
+        for name, expected in data['files'].items():
+            target = (package / name).resolve()
+            if not target.is_relative_to(package.resolve()) or digest(target) != expected:
+                raise SetupError(f'Packaged artifact integrity failure: {name}')
+        if not data['runtime_tag'].startswith(data['version'] + '-') or '/' in data['runtime_tag']:
+            raise SetupError('Invalid runtime identity.')
+        return data
+    except (KeyError, TypeError, ValueError) as error:
+        raise SetupError('Invalid release metadata.') from error
+    except FileNotFoundError as error:
+        raise PrerequisiteError('An intact npm artifact is required; use excuse setup or pass --package-root PATH.') from error
+
+
+def home() -> Path:
+    override = os.environ.get('EXCUSE_OPS_HOME')
+    return Path(override).expanduser().resolve() if override else Path.home() / 'Library' / 'Application Support' / 'ExcuseOps'
+
+
+def runtime_path(data: dict) -> Path:
+    return home() / 'runtimes' / data['runtime_tag']
+
+
+def identity(data: dict) -> dict:
+    return {key: data[key] for key in ('version', 'runtime_tag', 'files', 'python', 'platform', 'arch')}
+
+
+def _atomic_json(path: Path, value: dict) -> None:
+    temporary = path.with_name(path.name + f'.{os.getpid()}.tmp')
+    try:
+        with temporary.open('x') as stream:
+            json.dump(value, stream, sort_keys=True)
+            stream.flush()
+            os.fsync(stream.fileno())
+        temporary.replace(path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+@contextmanager
+def _ownership(lock: Path, data: dict) -> Iterator[None]:
+    try:
+        stream = lock.open('x')
+    except FileExistsError as error:
+        raise SetupError(f'Setup ownership already exists: {lock}. Verify its PID and recover explicitly; no automatic lock removal.') from error
+    try:
+        with stream:
+            json.dump({'pid': os.getpid(), 'runtime_tag': data['runtime_tag']}, stream)
+        yield
+    finally:
+        lock.unlink()
+
+
+def _verify(directory: Path, data: dict) -> bool:
+    python = directory / 'bin' / 'python'
+    if not python.exists():
+        return False
+    script = '''import importlib,importlib.metadata as m,json,sys,z3
+expected=json.loads(sys.argv[1])
+assert list(sys.version_info[:3]) == expected['python']
+assert sys.prefix != sys.base_prefix
+assert m.version('excuse-ops') == expected['version']
+assert m.version('z3-solver') == expected['solver_version']
+for name in expected['modules']: importlib.import_module('excuse_ops.'+name)
+x=z3.Int('setup_probe'); solver=z3.Solver(); solver.add(x==7)
+assert solver.check()==z3.sat and solver.model().eval(x).as_long()==7
+'''
+    result = subprocess.run([str(python), '-I', '-c', script, json.dumps(data)], capture_output=True, text=True, timeout=30)
+    return result.returncode == 0
+
+
+def _install(directory: Path, package: Path, data: dict) -> None:
+    venv.EnvBuilder(with_pip=True).create(directory)
+    requirements = directory / 'release-requirements.txt'
+    wheel = package / data['wheel']
+    requirements.write_text((package / 'requirements.lock').read_text() + '\n' + wheel.as_uri() + ' --hash=sha256:' + data['files'][data['wheel']] + '\n')
+    # An explicitly approved retry must repair files even if installed metadata
+    # still claims the correct version after an interrupted/corrupt installation.
+    subprocess.run([
+        str(directory / 'bin' / 'python'), '-I', '-m', 'pip', '--isolated', 'install',
+        '--disable-pip-version-check', '--no-input', '--only-binary=:all:',
+        '--require-hashes', '--force-reinstall', '-r', str(requirements),
+    ], check=True)
+
+
+def setup(package: Path) -> int:
+    package = package.resolve()
+    data = release(package)
+    if (sys.implementation.name != 'cpython' or list(sys.version_info[:3]) != data['python']
+            or sys.platform != data['platform'] or platform.machine() != data['arch']):
+        raise PrerequisiteError(f"This release requires CPython {'.'.join(map(str,data['python']))} on {data['platform']}/{data['arch']}.")
+    directory = runtime_path(data)
+    lock = directory.parent / ('.' + data['runtime_tag'] + '.setup.lock')
+    ready = directory / 'ready.json'
+    owner = directory / 'owner.json'
+    expected = identity(data)
+    if lock.exists():
+        raise SetupError(f'Setup ownership exists: {lock}; verify its PID before explicit recovery.')
+    if directory.exists():
+        if directory.is_symlink() or not owner.is_file() or json.loads(owner.read_text()) != expected:
+            raise SetupError(f'Refusing to modify an unknown/incompatible directory: {directory}')
+        if ready.is_file() and json.loads(ready.read_text()) == expected and _verify(directory, data):
+            print(f'Runtime verified and reused: {directory}')
+            return 0
+    print(f'Runtime: {directory}')
+    print(f"Installs bundled ExcuseOps {data['version']} and downloads hash-pinned z3-solver {data['solver_version']}. System Python and project data are not changed.")
+    try:
+        answer = input('Install/repair this isolated runtime? [y/N]: ').strip().lower()
+    except EOFError:
+        answer = ''
+    if answer not in ('y', 'yes'):
+        print('Cancelled. Nothing installed.')
+        return 0
+    directory.parent.mkdir(parents=True, exist_ok=True)
+    with _ownership(lock, data):
+        # Recheck after acquiring ownership: another setup may have completed
+        # while this process was waiting for consent.
+        if directory.exists():
+            if directory.is_symlink() or not owner.is_file() or json.loads(owner.read_text()) != expected:
+                raise SetupError(f'Refusing to modify an unknown/incompatible directory: {directory}')
+            if ready.is_file() and json.loads(ready.read_text()) == expected and _verify(directory, data):
+                print(f'Runtime verified and reused: {directory}')
+                return 0
+        else:
+            directory.mkdir()
+            _atomic_json(owner, expected)
+        ready.unlink(missing_ok=True)
+        _install(directory, package, data)
+        if not _verify(directory, data):
+            raise SetupError('Installed runtime failed application/Z3 verification; not marked ready. Run setup to retry.')
+        _atomic_json(ready, expected)
+    print(f'Runtime ready: {directory}')
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog='excuse setup', allow_abbrev=False)
+    parser.add_argument('--package-root', type=Path, default=Path(__file__).resolve().parent)
+    args = parser.parse_args(argv)
+    try:
+        return setup(args.package_root)
+    except PrerequisiteError as error:
+        print(str(error), file=sys.stderr)
+        return 2
+    except (SetupError, OSError, ValueError, subprocess.SubprocessError) as error:
+        print(f'Setup failed: {error}', file=sys.stderr)
+        return 4
+    except KeyboardInterrupt:
+        print('Setup interrupted; no incomplete runtime was marked ready.', file=sys.stderr)
+        return 130
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/package.json

@@ -1,6 +1,41 @@
 {
+  "bin": {
+    "excuse": "bin/excuse.mjs"
+  },
+  "bugs": {
+    "url": "https://github.com/danilocasim/excuse-ops/issues"
+  },
+  "cpu": [
+    "arm64"
+  ],
+  "description": "Local-first version control for your personal mythology",
+  "engines": {
+    "node": "26.7.0"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "bin/excuse.mjs",
+    "bootstrap.py",
+    "release.json",
+    "requirements.lock",
+    "artifacts/excuse_ops-0.1.0-py3-none-any.whl"
+  ],
+  "homepage": "https://github.com/danilocasim/excuse-ops#readme",
+  "license": "MIT",
   "name": "excuse-ops",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "os": [
+    "darwin"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "next"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danilocasim/excuse-ops.git"
+  },
+  "type": "module",
+  "version": "0.1.0"
+}

package/release.json

@@ -0,0 +1,33 @@
+{
+  "arch": "arm64",
+  "files": {
+    "artifacts/excuse_ops-0.1.0-py3-none-any.whl": "aff2ab6c74530a04f5d88fbc071d4adeb05eaa5222041f83aa078482a8781ddc",
+    "bootstrap.py": "44ec6e6711f53bfb62b306a0317e73f1c2db9454b8e7963045e564dba2733f6d",
+    "requirements.lock": "7f30566ba72b3ed4e8d24fa601d7b972273215312c3ef7604bebfba7c25995d3"
+  },
+  "modules": [
+    "__init__",
+    "application",
+    "bootstrap",
+    "checker",
+    "cli",
+    "domain",
+    "history",
+    "parser",
+    "repair",
+    "reports",
+    "storage"
+  ],
+  "node": "26.7.0",
+  "platform": "darwin",
+  "python": [
+    3,
+    14,
+    6
+  ],
+  "runtime_tag": "0.1.0-darwin-arm64-cpython-3146-aff2ab6c74530a04",
+  "schema": 1,
+  "solver_version": "4.16.0.0",
+  "version": "0.1.0",
+  "wheel": "artifacts/excuse_ops-0.1.0-py3-none-any.whl"
+}

package/requirements.lock

@@ -0,0 +1 @@
+z3-solver==4.16.0.0 --hash=sha256:cc52843cfdd3d3f2cd24bedc62e71c18af8c8b7b23fb05e639ab60b01b5f8f2f