agent-scenario-loop 0.1.2 → 0.1.4

package/dist/scripts/release-readiness.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/scripts/release-readiness.js

@@ -0,0 +1,520 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const REQUIRED_BIN_TARGETS = {
+    'agent-scenario-loop': 'dist/runner/check-plan.js',
+    'asl-agent-device': 'dist/runner/agent-device.js',
+    'asl-android-adb': 'dist/runner/android-adb.js',
+    'asl-argent': 'dist/runner/argent.js',
+    'asl-check-plan': 'dist/runner/check-plan.js',
+    'asl-compare': 'dist/runner/compare.js',
+    'asl-compare-latest': 'dist/runner/compare-latest.js',
+    'asl-demo-loop': 'dist/runner/demo-loop.js',
+    'asl-example-android-live': 'dist/runner/example-android-live.js',
+    'asl-example-ios-live': 'dist/runner/example-ios-live.js',
+    'asl-host-doctor': 'dist/runner/host-doctor.js',
+    'asl-init': 'dist/runner/init-project.js',
+    'asl-ios-simctl': 'dist/runner/ios-simctl.js',
+    'asl-live-android': 'dist/runner/live-android.js',
+    'asl-live-ios': 'dist/runner/live-ios.js',
+    'asl-live-proof': 'dist/runner/live-proof.js',
+    'asl-profile-android': 'dist/runner/profile-android.js',
+    'asl-profile-ios': 'dist/runner/profile-ios.js',
+    'asl-validate-project': 'dist/runner/validate-project.js',
+};
+const REQUIRED_EXPORTS = {
+    '.': {
+        require: './dist/index.js',
+        types: './dist/index.d.ts',
+        import: './dist/index.js',
+        default: './dist/index.js',
+    },
+    './app/profile-session': {
+        require: './app/profile-session.ts',
+        types: './app/profile-session.ts',
+        import: './app/profile-session.ts',
+        default: './app/profile-session.ts',
+    },
+    './examples/*': './examples/*',
+    './package.json': './package.json',
+    './runner/agent-device': {
+        require: './dist/runner/agent-device.js',
+        types: './dist/runner/agent-device.d.ts',
+        import: './dist/runner/agent-device.js',
+        default: './dist/runner/agent-device.js',
+    },
+    './runner/agent-device-driver': {
+        require: './dist/runner/agent-device-driver.js',
+        types: './dist/runner/agent-device-driver.d.ts',
+        import: './dist/runner/agent-device-driver.js',
+        default: './dist/runner/agent-device-driver.js',
+    },
+    './runner/argent-driver': {
+        require: './dist/runner/argent-driver.js',
+        types: './dist/runner/argent-driver.d.ts',
+        import: './dist/runner/argent-driver.js',
+        default: './dist/runner/argent-driver.js',
+    },
+    './runner/argent': {
+        require: './dist/runner/argent.js',
+        types: './dist/runner/argent.d.ts',
+        import: './dist/runner/argent.js',
+        default: './dist/runner/argent.js',
+    },
+    './runner/android-adb': {
+        require: './dist/runner/android-adb.js',
+        types: './dist/runner/android-adb.d.ts',
+        import: './dist/runner/android-adb.js',
+        default: './dist/runner/android-adb.js',
+    },
+    './runner/android-adb-driver': {
+        require: './dist/runner/android-adb-driver.js',
+        types: './dist/runner/android-adb-driver.d.ts',
+        import: './dist/runner/android-adb-driver.js',
+        default: './dist/runner/android-adb-driver.js',
+    },
+    './runner/check-plan': {
+        require: './dist/runner/check-plan.js',
+        types: './dist/runner/check-plan.d.ts',
+        import: './dist/runner/check-plan.js',
+        default: './dist/runner/check-plan.js',
+    },
+    './runner/compare': {
+        require: './dist/runner/compare.js',
+        types: './dist/runner/compare.d.ts',
+        import: './dist/runner/compare.js',
+        default: './dist/runner/compare.js',
+    },
+    './runner/compare-latest': {
+        require: './dist/runner/compare-latest.js',
+        types: './dist/runner/compare-latest.d.ts',
+        import: './dist/runner/compare-latest.js',
+        default: './dist/runner/compare-latest.js',
+    },
+    './runner/demo-loop': {
+        require: './dist/runner/demo-loop.js',
+        types: './dist/runner/demo-loop.d.ts',
+        import: './dist/runner/demo-loop.js',
+        default: './dist/runner/demo-loop.js',
+    },
+    './runner/example-android-live': {
+        require: './dist/runner/example-android-live.js',
+        types: './dist/runner/example-android-live.d.ts',
+        import: './dist/runner/example-android-live.js',
+        default: './dist/runner/example-android-live.js',
+    },
+    './runner/example-ios-live': {
+        require: './dist/runner/example-ios-live.js',
+        types: './dist/runner/example-ios-live.d.ts',
+        import: './dist/runner/example-ios-live.js',
+        default: './dist/runner/example-ios-live.js',
+    },
+    './runner/host-doctor': {
+        require: './dist/runner/host-doctor.js',
+        types: './dist/runner/host-doctor.d.ts',
+        import: './dist/runner/host-doctor.js',
+        default: './dist/runner/host-doctor.js',
+    },
+    './runner/init-project': {
+        require: './dist/runner/init-project.js',
+        types: './dist/runner/init-project.d.ts',
+        import: './dist/runner/init-project.js',
+        default: './dist/runner/init-project.js',
+    },
+    './runner/ios-simctl': {
+        require: './dist/runner/ios-simctl.js',
+        types: './dist/runner/ios-simctl.d.ts',
+        import: './dist/runner/ios-simctl.js',
+        default: './dist/runner/ios-simctl.js',
+    },
+    './runner/ios-simctl-driver': {
+        require: './dist/runner/ios-simctl-driver.js',
+        types: './dist/runner/ios-simctl-driver.d.ts',
+        import: './dist/runner/ios-simctl-driver.js',
+        default: './dist/runner/ios-simctl-driver.js',
+    },
+    './runner/live-android': {
+        require: './dist/runner/live-android.js',
+        types: './dist/runner/live-android.d.ts',
+        import: './dist/runner/live-android.js',
+        default: './dist/runner/live-android.js',
+    },
+    './runner/live-ios': {
+        require: './dist/runner/live-ios.js',
+        types: './dist/runner/live-ios.d.ts',
+        import: './dist/runner/live-ios.js',
+        default: './dist/runner/live-ios.js',
+    },
+    './runner/live-proof': {
+        require: './dist/runner/live-proof.js',
+        types: './dist/runner/live-proof.d.ts',
+        import: './dist/runner/live-proof.js',
+        default: './dist/runner/live-proof.js',
+    },
+    './runner/profile-android': {
+        require: './dist/runner/profile-android.js',
+        types: './dist/runner/profile-android.d.ts',
+        import: './dist/runner/profile-android.js',
+        default: './dist/runner/profile-android.js',
+    },
+    './runner/profile-ios': {
+        require: './dist/runner/profile-ios.js',
+        types: './dist/runner/profile-ios.d.ts',
+        import: './dist/runner/profile-ios.js',
+        default: './dist/runner/profile-ios.js',
+    },
+    './runner/validate-project': {
+        require: './dist/runner/validate-project.js',
+        types: './dist/runner/validate-project.d.ts',
+        import: './dist/runner/validate-project.js',
+        default: './dist/runner/validate-project.js',
+    },
+    './schemas/*': './schemas/*',
+    './templates/*': './templates/*',
+};
+const REQUIRED_PACKAGE_FILES = [
+    'LICENSE',
+    'README.md',
+    'app/profile-session.ts',
+    'core/config-template.json',
+    'dist',
+    'docs',
+    'examples',
+    'schemas',
+    'templates',
+];
+const REQUIRED_PACKAGE_EXCLUSIONS = [
+    '!dist/**/__tests__',
+    '!examples/mobile-app/.expo',
+    '!examples/mobile-app/.expo/**',
+    '!examples/mobile-app/android',
+    '!examples/mobile-app/android/**',
+    '!examples/mobile-app/artifacts',
+    '!examples/mobile-app/artifacts/**',
+    '!examples/mobile-app/ios',
+    '!examples/mobile-app/ios/**',
+    '!examples/mobile-app/node_modules',
+    '!examples/mobile-app/node_modules/**',
+];
+const REQUIRED_GITIGNORE_ENTRIES = [
+    'node_modules/',
+    '.agents/',
+    'dist/',
+    'core/artifacts/',
+    'artifacts/',
+    'examples/mobile-app/.expo/',
+    'examples/mobile-app/android/',
+    'examples/mobile-app/artifacts/',
+    'examples/mobile-app/ios/',
+    'examples/mobile-app/node_modules/',
+];
+const FORBIDDEN_TRACKED_PATH_PATTERNS = [
+    /^artifacts\//u,
+    /^core\/artifacts\//u,
+    /^dist\//u,
+    /^examples\/mobile-app\/(?:\.expo|android|artifacts|ios|node_modules)(?:\/|$)/u,
+];
+const REQUIRED_CONFIG_STRING_FIELDS = [
+    ['app', 'profileSessionScheme'],
+    ['app', 'iosBundleId'],
+    ['app', 'androidPackage'],
+    ['paths', 'artifactRoot'],
+    ['paths', 'iosArtifactsRoot'],
+    ['paths', 'androidArtifactsRoot'],
+    ['paths', 'scenarioRoot'],
+];
+const REQUIRED_PLATFORM_SCRIPT_PAIRS = [
+    ['asl:check:ios', 'asl:check:android'],
+    ['asl:profile:ios', 'asl:profile:android'],
+    ['asl:profile:ios:provider', 'asl:profile:android:provider'],
+    ['asl:profile:ios:live', 'asl:profile:android:live'],
+    ['asl:ios:live', 'asl:android:live'],
+    ['asl:ios:live:agent-device', 'asl:android:live:agent-device'],
+    ['asl:ios:live:argent', 'asl:android:live:argent'],
+    ['asl:ios:live:runners', 'asl:android:live:runners'],
+    ['asl:agent-device:ios', 'asl:agent-device:android'],
+    ['asl:argent:ios', 'asl:argent:android'],
+    ['asl:compare:ios', 'asl:compare:android'],
+    ['asl:live-proof:ios', 'asl:live-proof:android'],
+];
+const REQUIRED_STRICT_EXAMPLE_LIVE_SCRIPTS = [
+    'example:android:live',
+    'example:android:live:agent-device',
+    'example:android:live:argent',
+    'example:android:live:runners',
+    'example:ios:live',
+    'example:ios:live:agent-device',
+    'example:ios:live:argent',
+    'example:ios:live:runners',
+];
+/**
+ * Reads and parses a JSON object from disk.
+ *
+ * @param {string} filePath
+ * @returns {Record<string, unknown>}
+ */
+function readJsonObject(filePath) {
+    const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    assert.equal(typeof value, 'object', `${filePath} must contain a JSON object`);
+    assert.notEqual(value, null, `${filePath} must contain a JSON object`);
+    assert.equal(Array.isArray(value), false, `${filePath} must contain a JSON object`);
+    return value;
+}
+/**
+ * Reads a nested value from a JSON object.
+ *
+ * @param {Record<string, unknown>} object
+ * @param {string[]} pathSegments
+ * @returns {unknown}
+ */
+function readNestedValue(object, pathSegments) {
+    let value = object;
+    for (const segment of pathSegments) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            return undefined;
+        }
+        value = value[segment];
+    }
+    return value;
+}
+/**
+ * Returns a string map property from a JSON object.
+ *
+ * @param {Record<string, unknown>} object
+ * @param {string} key
+ * @returns {Record<string, string>}
+ */
+function getStringMap(object, key) {
+    const value = object[key];
+    assert.equal(typeof value, 'object', `${key} must be an object`);
+    assert.notEqual(value, null, `${key} must be an object`);
+    assert.equal(Array.isArray(value), false, `${key} must be an object`);
+    for (const [entryKey, entryValue] of Object.entries(value)) {
+        assert.equal(typeof entryValue, 'string', `${key}.${entryKey} must be a string`);
+    }
+    return value;
+}
+/**
+ * Returns an object map property from a JSON object.
+ *
+ * @param {Record<string, unknown>} object
+ * @param {string} key
+ * @returns {Record<string, unknown>}
+ */
+function getObjectMap(object, key) {
+    const value = object[key];
+    assert.equal(typeof value, 'object', `${key} must be an object`);
+    assert.notEqual(value, null, `${key} must be an object`);
+    assert.equal(Array.isArray(value), false, `${key} must be an object`);
+    return value;
+}
+/**
+ * Returns a string array property from a JSON object.
+ *
+ * @param {Record<string, unknown>} object
+ * @param {string} key
+ * @returns {string[]}
+ */
+function getStringArray(object, key) {
+    const value = object[key];
+    assert.equal(Array.isArray(value), true, `${key} must be an array`);
+    for (const entry of value) {
+        assert.equal(typeof entry, 'string', `${key} entries must be strings`);
+    }
+    return value;
+}
+/**
+ * Asserts that every expected value appears in an actual string list.
+ *
+ * @param {string[]} actual
+ * @param {string[]} expected
+ * @param {string} label
+ * @returns {void}
+ */
+function assertIncludesAll(actual, expected, label) {
+    for (const entry of expected) {
+        assert.equal(actual.includes(entry), true, `${label} is missing ${entry}`);
+    }
+}
+/**
+ * Asserts that package metadata still describes the intended public package.
+ *
+ * @param {Record<string, unknown>} packageJson
+ * @returns {void}
+ */
+function assertPublicPackageMetadata(packageJson) {
+    assert.equal(packageJson.name, 'agent-scenario-loop');
+    assert.match(String(packageJson.version), /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u);
+    assert.equal(packageJson.private, false);
+    assert.equal(packageJson.license, 'MIT');
+    assert.equal(packageJson.type, 'commonjs');
+    assert.equal(packageJson.main, 'dist/index.js');
+    assert.equal(packageJson.types, 'dist/index.d.ts');
+    assert.equal(getObjectMap(packageJson, 'publishConfig').access, 'public');
+    assert.equal(getObjectMap(packageJson, 'engines').node, '>=20');
+}
+/**
+ * Asserts that release scripts keep npm publishing behind the full validation gate.
+ *
+ * @param {Record<string, unknown>} packageJson
+ * @returns {void}
+ */
+function assertReleaseScripts(packageJson) {
+    const scripts = getStringMap(packageJson, 'scripts');
+    assert.equal(scripts.prepublishOnly, 'pnpm release:check');
+    assert.equal(scripts['release:readiness'], 'pnpm build && node dist/scripts/release-readiness.js');
+    assert.equal(scripts['release:check'], 'pnpm test && pnpm release:readiness && pnpm package:smoke && pnpm consumer:rehearse');
+    assert.equal(scripts['package:smoke'], 'pnpm build && node dist/scripts/package-smoke.js');
+    assert.equal(scripts['consumer:rehearse'], 'pnpm build && node dist/scripts/consumer-rehearsal.js');
+    assert.equal(scripts['downstream:local-package'], 'pnpm build && node dist/scripts/downstream-local-package-gate.js');
+    for (const scriptName of REQUIRED_STRICT_EXAMPLE_LIVE_SCRIPTS) {
+        assert.match(scripts[scriptName], /--compare-latest/u, `${scriptName} must write comparison evidence by default`);
+        assert.match(scripts[scriptName], /--fail-on-regression/u, `${scriptName} must fail on regressions by default`);
+    }
+    assert.match(scripts['example:mobile:live-proof'], /--require-platforms android,ios/u);
+    assert.match(scripts['example:mobile:live-proof'], /--out artifacts\/example-mobile-app\/live-proof-set/u);
+    assert.match(scripts['example:mobile:live-proof'], /--fail-on-regression/u);
+    assert.match(scripts['example:app:start:isolated'], /--port 8097 --host localhost --clear/u);
+}
+/**
+ * Asserts that public binaries and package subpath exports map to built files.
+ *
+ * @param {Record<string, unknown>} packageJson
+ * @returns {void}
+ */
+function assertPublicEntrypoints(packageJson) {
+    assert.deepEqual(getStringMap(packageJson, 'bin'), REQUIRED_BIN_TARGETS);
+    assert.deepEqual(getObjectMap(packageJson, 'exports'), REQUIRED_EXPORTS);
+}
+/**
+ * Extracts documented runner subpath specifiers from the public API guide.
+ *
+ * @param {string} repoRoot
+ * @returns {string[]}
+ */
+function readDocumentedRunnerSubpaths(repoRoot) {
+    const apiDocs = fs.readFileSync(path.join(repoRoot, 'docs', 'api.md'), 'utf8');
+    const subpaths = new Set();
+    for (const match of apiDocs.matchAll(/`(agent-scenario-loop\/runner\/[^`]+)`/gu)) {
+        subpaths.add(match[1]);
+    }
+    return Array.from(subpaths).sort();
+}
+/**
+ * Extracts concrete runner subpath specifiers from package exports.
+ *
+ * @param {Record<string, unknown>} packageJson
+ * @returns {string[]}
+ */
+function readExportedRunnerSubpaths(packageJson) {
+    return Object.keys(getObjectMap(packageJson, 'exports'))
+        .filter((subpath) => subpath.startsWith('./runner/'))
+        .map((subpath) => `agent-scenario-loop/${subpath.slice(2)}`)
+        .sort();
+}
+/**
+ * Asserts that the public API guide and package exports describe the same runner surface.
+ *
+ * @param {Record<string, unknown>} packageJson
+ * @param {string} repoRoot
+ * @returns {void}
+ */
+function assertPublicApiDocs(packageJson, repoRoot) {
+    assert.deepEqual(readDocumentedRunnerSubpaths(repoRoot), readExportedRunnerSubpaths(packageJson), 'docs/api.md runner subpaths must match package.json exports');
+}
+/**
+ * Asserts that package include/exclude metadata protects generated local state.
+ *
+ * @param {Record<string, unknown>} packageJson
+ * @returns {void}
+ */
+function assertPackageFileList(packageJson) {
+    const files = getStringArray(packageJson, 'files');
+    assertIncludesAll(files, REQUIRED_PACKAGE_FILES, 'package files');
+    assertIncludesAll(files, REQUIRED_PACKAGE_EXCLUSIONS, 'package files');
+    for (const forbidden of ['.github', 'scripts', 'runner', 'node_modules', 'artifacts']) {
+        assert.equal(files.includes(forbidden), false, `package files must not include ${forbidden}`);
+    }
+}
+/**
+ * Asserts that ignored local state paths remain explicit in the repository.
+ *
+ * @param {string} repoRoot
+ * @returns {void}
+ */
+function assertGitignoreState(repoRoot) {
+    const gitignore = fs.readFileSync(path.join(repoRoot, '.gitignore'), 'utf8').split(/\r?\n/u);
+    assertIncludesAll(gitignore, REQUIRED_GITIGNORE_ENTRIES, '.gitignore');
+}
+/**
+ * Asserts that generated runtime/native state is not tracked by git.
+ *
+ * @param {string} repoRoot
+ * @returns {void}
+ */
+function assertNoTrackedGeneratedState(repoRoot) {
+    const output = execFileSync('git', ['ls-files', '-z'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const trackedPaths = output.split('\0').filter(Boolean);
+    for (const trackedPath of trackedPaths) {
+        assert.equal(FORBIDDEN_TRACKED_PATH_PATTERNS.some((pattern) => pattern.test(trackedPath)), false, `generated state must not be tracked: ${trackedPath}`);
+    }
+}
+/**
+ * Asserts that shipped config templates contain identifiers needed by both mobile platforms.
+ *
+ * @param {string} repoRoot
+ * @returns {void}
+ */
+function assertConfigTemplates(repoRoot) {
+    for (const relativePath of ['core/config-template.json', 'templates/project.config.json']) {
+        const config = readJsonObject(path.join(repoRoot, relativePath));
+        for (const fieldPath of REQUIRED_CONFIG_STRING_FIELDS) {
+            const value = readNestedValue(config, fieldPath);
+            assert.equal(typeof value, 'string', `${relativePath} must include ${fieldPath.join('.')}`);
+            assert.notEqual(String(value).trim(), '', `${relativePath} must include non-empty ${fieldPath.join('.')}`);
+        }
+    }
+}
+/**
+ * Asserts that shipped package-script snippets expose paired iOS and Android lanes.
+ *
+ * @param {string} repoRoot
+ * @returns {void}
+ */
+function assertPlatformPackageScripts(repoRoot) {
+    for (const relativePath of ['templates/package-scripts.json', 'examples/mobile-app/asl/package-scripts.json']) {
+        const scripts = readJsonObject(path.join(repoRoot, relativePath));
+        for (const [iosScriptName, androidScriptName] of REQUIRED_PLATFORM_SCRIPT_PAIRS) {
+            assert.equal(typeof scripts[iosScriptName], 'string', `${relativePath} must include ${iosScriptName}`);
+            assert.equal(typeof scripts[androidScriptName], 'string', `${relativePath} must include ${androidScriptName}`);
+        }
+    }
+}
+/**
+ * Runs the release-readiness assertions for the current repository checkout.
+ *
+ * @returns {void}
+ */
+function main() {
+    const repoRoot = path.resolve(__dirname, '..', '..');
+    const packageJson = readJsonObject(path.join(repoRoot, 'package.json'));
+    assertPublicPackageMetadata(packageJson);
+    assertReleaseScripts(packageJson);
+    assertPublicEntrypoints(packageJson);
+    assertPublicApiDocs(packageJson, repoRoot);
+    assertPackageFileList(packageJson);
+    assertGitignoreState(repoRoot);
+    assertNoTrackedGeneratedState(repoRoot);
+    assertConfigTemplates(repoRoot);
+    assertPlatformPackageScripts(repoRoot);
+    process.stdout.write('release readiness passed\n');
+}
+main();

package/docs/adapters.md

@@ -102,6 +102,8 @@ The built-in adb and simctl adapters show the expected boundary:
 
 External tools such as agent-device, Argent, XcodeBuildMCP, axe, profilers, and custom scripts should plug in behind the same shape. The tactical tool can change; the scenario and artifact contract should not.
 
+Prefer capability-based orchestration over forcing one tool to own every surface. Use adb and simctl as the primary live profile capture lanes for app launch, logs, screenshots, profile-session truth, and causal timelines. Attach heavier or tool-specific diagnostics after the active profile window through provider commands or rehydration. Agent Device is a good fit for Android snapshots and cross-platform network/performance evidence when its session is bound to the target. Argent is a good fit for iOS accessibility descriptions when `describe` can return AXRuntime evidence; native hierarchy, video, trace, React DevTools, and long profiler captures should be explicit heavy lanes until a runner/provider maps them into stable ASL artifacts.
+
 ## Preserve Evidence
 
 Every run should leave agent-readable proof:
@@ -133,7 +135,7 @@ asl-profile-android \
   --capture screenshot:artifacts/provider/final-screen.png
 ```
 
-If the provider should run during profiling, declare `providerCommands` in its manifest. Commands run without a shell, preserve stdout/stderr/exit code, and inventory outputs in `manifest.artifacts.evidenceAttachments`. Runtime profiles reject a provider whose `platforms` do not include the selected platform before command execution, preserving the same active-provider semantics used by planner compatibility.
+If the provider should run during profile artifact assembly, declare `providerCommands` in its manifest. Profile runners execute provider commands after the selected platform evidence source is available, including live `--adb-capture` / `--simctl-capture` runs and later `--adb-artifacts` / `--simctl-artifacts` rehydration runs. Use `phase: "afterCapture"` for diagnostics collected from an existing capture sidecar; use `phase: "postRun"` for evidence that should be understood as post-profile enrichment. Commands run without a shell, preserve stdout/stderr/exit code, and inventory outputs in `manifest.artifacts.evidenceAttachments`. Provider command outputs may set `required: true` so the matching diagnostic inventory entry is required when the provider successfully captures that output; scenario-authored required artifacts and capabilities remain canonical too. Runtime profiles reject a provider whose `platforms` do not include the selected platform before command execution, preserving the same active-provider semantics used by planner compatibility.
 
 ## Acceptance Checklist
 
@@ -143,3 +145,7 @@ If the provider should run during profiling, declare `providerCommands` in its m
 - Passed runs write the standard artifact set.
 - Attached evidence is inventoried with stable run-relative paths.
 - Package docs describe whether the adapter is bundled, a fixture target, or a project-local integration.
+
+## Read next
+
+- [Consumer App Rehearsal](consumer-rehearsal.md) for adopting the package inside an existing app

package/docs/api.md

@@ -80,11 +80,11 @@ For concrete runner and evidence-provider integration steps, see [Adapter Onboar
 
 ## App Helper
 
-`app/profile-session.ts` is shipped as source for React Native apps to copy into their own codebase. It is not a compiled CommonJS runtime export because it depends on app-side React Native modules, app bundling, and platform storage behavior.
+`agent-scenario-loop/app/profile-session` is shipped as React Native source. Apps can copy `app/profile-session.ts` into their own codebase or re-export the package subpath from an app-local helper module. It is not a compiled CommonJS runtime export because it depends on app-side React Native modules, app bundling, and platform storage behavior.
 
 The intended integration is:
 
-1. Copy `app/profile-session.ts` into the app.
+1. Copy `app/profile-session.ts` into the app, or re-export `agent-scenario-loop/app/profile-session` from an app-local helper.
 2. Wire `useProfileSessionBootstrap()` once near the app root.
 3. Emit app-owned truth events with `emitProfileEvent()`.
 4. Register optional command targets with `registerProfileCommandTargetHandler()`.

package/docs/architecture.md

@@ -0,0 +1,90 @@
+# Architecture
+
+ASL is implemented in TypeScript, but its contracts are language-neutral.
+
+The TypeScript package is the reference implementation for planning, execution,
+schema validation, artifact writing, health/verdict/comparison interpretation,
+run indexing, CLIs, the TypeScript runner SDK, and the React Native/Expo helper.
+Those implementation modules are not the interoperability contract.
+
+## Contract Boundary
+
+JSON Schema and normative documentation are the source of truth for external
+participants. TypeScript interfaces should reflect those contracts, not replace
+them.
+
+Language-neutral contracts include:
+
+- scenario schemas;
+- runner and evidence-provider manifests;
+- capability definitions;
+- truth-event envelopes;
+- command and result envelopes;
+- lifecycle states;
+- error taxonomy;
+- artifact schemas;
+- cancellation and timeout semantics;
+- protocol-version negotiation.
+
+External adapters must be able to participate out of process. A valid adapter
+may be an executable written in Swift, Kotlin, Python, Rust, shell, TypeScript,
+or another language, provided it satisfies the documented schemas and protocol.
+The minimal executable protocol is described in
+[External Adapter Protocol](external-adapter-protocol.md).
+
+## Reference Environments
+
+React Native and Expo remain the primary active battle-testing environment.
+They provide real Android and iOS pressure across lifecycle behavior, command
+transport, native boundaries, instrumentation, packaging, evidence provenance,
+and agent-facing summaries.
+
+The React Native helper is a reference transport. It does not define the truth
+event contract by itself. Native apps must be able to emit ASL truth events
+without embedding a JavaScript runtime.
+
+## Public Interoperability Rules
+
+- Scenario files must remain structured data, not arbitrary JavaScript.
+- Runners and providers must not be required to subclass TypeScript classes.
+- Large evidence should be passed by file reference, not embedded as base64.
+- External adapters should use structured protocol messages over stdio.
+- Messages should carry run ids, attempt ids, sequence numbers, operation ids,
+  deadlines, platform, clock-domain metadata, adapter identity, and artifact
+  references where applicable.
+- Failed operations should return structured failure data with stable codes,
+  classes, retryability, and next-action hints.
+
+## Audit Snapshot
+
+Current public contracts are JSON schemas and JSON manifests. Scenario fixtures
+are structured JSON and do not require callbacks or closures. Runner/provider
+manifests describe capabilities and commands as data.
+
+Known implementation-specific surfaces are intentionally reference paths:
+
+- npm package scripts and Node CLIs are the TypeScript distribution channel.
+- built-in adb, simctl, Argent, and agent-device runners are TypeScript
+  adapters.
+- React Native profile-session logging and AsyncStorage are reference truth
+  event transports.
+- provider command examples use Node scripts, but provider manifests can point
+  at any executable.
+
+These are acceptable as reference implementation details. They should not become
+requirements in scenario schemas, artifact schemas, or external-adapter protocol
+messages.
+
+## Future Design Test
+
+Could a Swift, Kotlin, Python, or Rust implementation satisfy this contract
+using only the schemas, protocol documentation, executable interface, and
+conformance fixtures?
+
+If yes, TypeScript remains a productive reference implementation. If no, the
+implementation-specific assumption should be identified and removed from the
+contract surface.
+
+## Read next
+
+- [External Adapter Protocol](external-adapter-protocol.md) for the out-of-process adapter envelope, operations, failures, and conformance fixture