@webex/internal-plugin-device 3.12.0-next.54 → 3.12.0-next.55

package/.sdd/manifest.json

@@ -0,0 +1,335 @@
+{
+  "manifest_version": 1,
+  "repository": {
+    "name": "@webex/internal-plugin-device",
+    "purpose": "Device registration for the Webex JS SDK: registers, refreshes, and unregisters this client's device with the WDM service and exposes the device-derived state (URLs, feature toggles, organization policy) as the webex.internal.device plugin.",
+    "category": "cat2-legacy",
+    "primary_languages": [
+      "javascript",
+      "typescript"
+    ]
+  },
+  "topology": "Single-repo",
+  "commands": {
+    "compile": {
+      "command": "yarn workspace @webex/internal-plugin-device build:src",
+      "source_file": "package.json",
+      "role": "compile"
+    },
+    "build": {
+      "command": "yarn workspace @webex/internal-plugin-device build",
+      "source_file": "package.json",
+      "role": "package"
+    },
+    "unit-test": {
+      "command": "yarn workspace @webex/internal-plugin-device test:unit",
+      "source_file": "package.json",
+      "role": "unit-test"
+    },
+    "browser-test": {
+      "command": "yarn workspace @webex/internal-plugin-device test:browser",
+      "source_file": "package.json",
+      "role": "integration-test"
+    },
+    "lint": {
+      "command": "yarn workspace @webex/internal-plugin-device test:style",
+      "source_file": "package.json",
+      "role": "lint"
+    },
+    "deploy": {
+      "command": "yarn workspace @webex/internal-plugin-device deploy:npm",
+      "source_file": "package.json",
+      "role": "deploy"
+    }
+  },
+  "toolchain": [
+    {
+      "name": "node",
+      "version": ">=18",
+      "origin": "repo-config",
+      "source_file": "package.json"
+    }
+  ],
+  "tests": {
+    "unit": {
+      "command_ref": "unit-test",
+      "dir": "test/unit",
+      "framework": "jest"
+    },
+    "integration": {
+      "command_ref": "browser-test",
+      "dir": "test/integration",
+      "framework": "mocha (karma runner)",
+      "external_deps": [
+        "Provisioned Webex test users via @webex/test-helper-test-users",
+        "Network access to Webex services"
+      ]
+    }
+  },
+  "quality_gates": {
+    "code_coverage": {
+      "origin": "none",
+      "declared_by": "riag@cisco.com via bootstrap questionnaire"
+    }
+  },
+  "coverage_status_definitions": {
+    "specced": ">=80% public surface specced, drift <5% — spec is authoritative",
+    "partial": "40-80% specced — spec is a hint, cross-check code",
+    "untracked": "<40% specced — code is the source of truth"
+  },
+  "modules": [
+    {
+      "path": "src/",
+      "coverage_status": "Partial",
+      "coverage_evidence": "Generator-side field measurement 80.0% (12 of 15 mandatory fields PRESENT, critical 6 of 7) assessed 2026-10-07. WEAK: external WDM integration (no committed machine-readable contract; owner states none can be provided, recorded as an approved unknown), test and characterization coverage (no baseline; MOD-015, INV-004, INV-005, MOD-026 untested), and design rationale (no accepted ADR). Provenance is PRESENT now that approval is recorded. Promotion to Specced held: a critical field is weak and no drift measurement exists.",
+      "canonical_spec": "src/docs/README.md",
+      "contracts": {
+        "provides": [
+          "device-plugin-sdk",
+          "device-registration-events",
+          "cisco-device-url-header"
+        ],
+        "requires": [
+          "wdm-device-registration-service",
+          "webex-core-plugin-host",
+          "webex-common-sdk",
+          "common-timers-sdk",
+          "http-core-sdk",
+          "internal-plugin-metrics-sdk"
+        ]
+      },
+      "last_assessed": "2026-10-07",
+      "section_profile": {
+        "has_ui": false,
+        "crosses_service_boundaries": true,
+        "enforces_domain_rules": true,
+        "is_concurrent_async": true,
+        "owns_persistence": false,
+        "returns_caller_errors": true,
+        "has_design_tradeoff": false,
+        "stateful_transitions": true,
+        "exposes_wire_protocol": false,
+        "ui_multi_screen": false,
+        "large_data_model": false,
+        "has_tiers": false,
+        "module_specific_conventions": true,
+        "published_package": true,
+        "embedded_in_host": false,
+        "holds_client_state": true,
+        "has_submodules": false,
+        "has_submodules_computed_by": "scripts/module_tree.py",
+        "has_submodules_computed_at": "2026-10-07T04:04:09Z",
+        "resolved_by": "claude-code/claude-sonnet-5-5 (host metadata; bootstrap questionnaire)",
+        "resolved_at": "2026-10-07T04:04:09Z"
+      }
+    }
+  ],
+  "contract_catalog": {
+    "index_path": "docs/architecture.md",
+    "definitions": {
+      "device-plugin-sdk": {
+        "kind": "sdk",
+        "publication": "published",
+        "source_kind": "repository-path",
+        "source": "package.json",
+        "summary": "Published npm package surface declared by package.json (main: dist/index.js, devMain: src/index.js): the default Device plugin registered as webex.internal.device, the config namespace webex.config.device, constants, CatalogDetails, DeviceRegistrationOptions, DeviceUrlInterceptor, and the feature classes exported from src/index.js. Internal plugin: semantic versioning is not strictly followed. Per-export detail lives in the owning module spec Public surface."
+      },
+      "device-registration-events": {
+        "kind": "event",
+        "publication": "published",
+        "source_kind": "repository-path",
+        "source": "src/device.js",
+        "summary": "Events on webex.internal.device: registration:success (name declared as DEVICE_EVENT_REGISTRATION_SUCCESS in src/constants.js, triggered in src/device.js), change and change:features (re-emitted by src/device.js), and change:<collection> for the developer, entitlement, and user feature collections (emitted by src/features/features-model.js; collection names declared in src/constants.js)."
+      },
+      "cisco-device-url-header": {
+        "kind": "http",
+        "publication": "internal",
+        "source_kind": "repository-path",
+        "source": "src/interceptors/device-url.js",
+        "summary": "cisco-device-url request header carrying the registered device URL, added by DeviceUrlInterceptor to outbound requests for catalog services other than idbroker, oauth, and saml."
+      },
+      "wdm-device-registration-service": {
+        "kind": "http",
+        "publication": "internal",
+        "source_kind": "external",
+        "source": "WDM service (Webex web device manager), reached through the wdm entry of the services catalog; no machine-readable contract is committed in this repository, and the response shape is exercised by the fixture test/unit/spec/wdm-dto.json",
+        "summary": "Device registration endpoints consumed by this module: POST wdm/devices to register, PUT and DELETE on the device url to refresh and unregister, and GET wdm/devices to list devices for cleanup."
+      },
+      "webex-core-plugin-host": {
+        "kind": "sdk",
+        "publication": "published",
+        "source_kind": "external",
+        "source": "@webex/webex-core (workspace package; no module spec, so source was used: WebexPlugin, persist, waitForValue, registerInternalPlugin, services plugin)",
+        "summary": "Plugin host contract consumed by this module: the WebexPlugin base model, the persist and waitForValue decorators, registerInternalPlugin, webex.request, and the services methods waitForCatalog, get, waitForService, getServiceFromUrl, convertUrlToPriorityHostUrl, and markFailedUrl."
+      },
+      "webex-common-sdk": {
+        "kind": "sdk",
+        "publication": "published",
+        "source_kind": "external",
+        "source": "@webex/common (workspace package; module spec consulted: oneFlight, deprecated, inBrowser, deviceType)",
+        "summary": "Shared primitives used here: oneFlight and deprecated decorators, the inBrowser flag, and the deviceType constants."
+      },
+      "common-timers-sdk": {
+        "kind": "sdk",
+        "publication": "published",
+        "source_kind": "external",
+        "source": "@webex/common-timers (workspace package; module spec consulted: safeSetTimeout)",
+        "summary": "safeSetTimeout, a setTimeout wrapper that unrefs the handle, used for the ephemeral refresh timer, the logout timer, and the registration wait."
+      },
+      "http-core-sdk": {
+        "kind": "sdk",
+        "publication": "published",
+        "source_kind": "external",
+        "source": "@webex/http-core (workspace package; module spec consulted: Interceptor)",
+        "summary": "The Interceptor base class extended by DeviceUrlInterceptor."
+      },
+      "internal-plugin-metrics-sdk": {
+        "kind": "sdk",
+        "publication": "published",
+        "source_kind": "external",
+        "source": "@webex/internal-plugin-metrics (workspace package; no module spec, so source was used: newMetrics.submitInternalEvent, newMetrics.callDiagnosticMetrics.setDeviceInfo, metrics.submitClientMetrics)",
+        "summary": "Metrics plugin API called during registration for internal events, call-diagnostic device info, and client metrics."
+      }
+    }
+  },
+  "spec_policy": {
+    "require_what_and_why": true,
+    "require_provenance": true,
+    "protected_specs": [
+      "src/docs/README.md"
+    ]
+  },
+  "validation": {
+    "generator_runtime": "claude-code",
+    "generator_model": "claude-sonnet-5-5",
+    "generator_run_id": "080ee7e9-bd3c-4dfc-a1ac-81cc28eec83f",
+    "generator_runtime_source": "host-metadata",
+    "validator_runtime": "01a114a2-39d4-73f2-b1b0-e0a3d977933d",
+    "validator_run_id": "01a114a2-39d4-73f2-b1b0-e0a3d977933d",
+    "validator_runtime_source": "host-metadata",
+    "minimum_independence": "different-runtime",
+    "runtime_fallback_tier": "different-runtime",
+    "blocking_severities": [
+      "Blocking"
+    ]
+  },
+  "layout": {
+    "sdd_root": ".sdd",
+    "docs_root": "docs",
+    "agent_entry_path": "AGENTS.md",
+    "standing_docs_root": "docs",
+    "spec_index_path": "docs/specs/README.md",
+    "module_docs_strategy": "source-local",
+    "module_docs_relative_path": "docs/README.md",
+    "module_docs_decision": {
+      "basis": "repo-standards-default",
+      "reason": "The package has no module-local documentation folder (the existing docs and src/docs directories were empty), documentation build, or protected authored file that collides with the source-local default.",
+      "decided_by": "claude-code (bootstrap questionnaire)",
+      "decided_at": "2026-10-07T04:04:09Z"
+    },
+    "repo_context_decision": {
+      "path": ".repo-context.json",
+      "schema_path": "schemas/repo-context.schema.json",
+      "action": "create",
+      "schema_action": "create",
+      "reason": "Neither the operational context nor its schema exists in this package; both are created from the bundled Repo Standards templates and verified repository evidence.",
+      "decided_by": "claude-code (bootstrap questionnaire)",
+      "decided_at": "2026-10-07T04:04:09Z"
+    },
+    "artifact_decisions": [
+      {
+        "path": "docs/service.md",
+        "action": "omit",
+        "reason": "The package is a published library, not a deployable service; it declares no deployment descriptor, container, or runtime entry point.",
+        "decided_by": "claude-code (bootstrap questionnaire)",
+        "decided_at": "2026-10-07T04:04:09Z"
+      },
+      {
+        "path": "mkdocs.yml",
+        "action": "omit",
+        "reason": "No documentation build exists for this package.",
+        "decided_by": "claude-code (bootstrap questionnaire)",
+        "decided_at": "2026-10-07T04:04:09Z"
+      },
+      {
+        "path": "api-specs/openapi.yaml",
+        "action": "omit",
+        "reason": "The package serves no HTTP routes; its published surface is the npm package declared in package.json, so no OpenAPI source applies.",
+        "decided_by": "claude-code (bootstrap questionnaire)",
+        "decided_at": "2026-10-07T04:04:09Z"
+      },
+      {
+        "path": "SECURITY.md",
+        "action": "omit",
+        "reason": "Absent at the package; the questionnaire did not select a security-policy artifact and no reporting contact is established.",
+        "decided_by": "claude-code (bootstrap questionnaire)",
+        "decided_at": "2026-10-07T04:04:09Z"
+      },
+      {
+        "path": "CONTRIBUTING.md",
+        "action": "omit",
+        "reason": "No package-level contribution guide exists; contribution rules are owned at the surrounding monorepo root.",
+        "decided_by": "claude-code (bootstrap questionnaire)",
+        "decided_at": "2026-10-07T04:04:09Z"
+      },
+      {
+        "path": "CHANGELOG.md",
+        "action": "omit",
+        "reason": "No package-level changelog exists; release notes are owned at the surrounding monorepo root.",
+        "decided_by": "claude-code (bootstrap questionnaire)",
+        "decided_at": "2026-10-07T04:04:09Z"
+      },
+      {
+        "path": "CTO_CHECKLIST.yml",
+        "action": "omit",
+        "reason": "The CTO readiness workflow applies to deployable services; this package is a published library.",
+        "decided_by": "claude-code (bootstrap questionnaire)",
+        "decided_at": "2026-10-07T04:04:09Z"
+      },
+      {
+        "path": "schemas/cto-checklist.schema.json",
+        "action": "omit",
+        "reason": "Selected together with CTO_CHECKLIST.yml, which is omitted.",
+        "decided_by": "claude-code (bootstrap questionnaire)",
+        "decided_at": "2026-10-07T04:04:09Z"
+      }
+    ],
+    "template_roots": {
+      "canonical": ".sdd/templates/repo-standards"
+    },
+    "repo_skills_root": ".sdd/skills",
+    "contract_index_path": "docs/architecture.md"
+  },
+  "substrate": {
+    "source": "WebexTools/repo-standards@d89a7fe59126ae3ad9bac9ca352aa7f12b4c85dc",
+    "consumed": [
+      "@webex/eslint-config-legacy and ESLint through package.json scripts",
+      "@webex/babel-config-legacy via babel.config.js",
+      "@webex/jest-config-legacy via jest.config.js",
+      "@webex/legacy-tools build and test runner via package.json",
+      "package README.md"
+    ],
+    "compliance_tier": "baseline"
+  },
+  "section_profiles": {
+    "repo": {
+      "owns_datastore": false,
+      "holds_client_state": true,
+      "components_interact": true,
+      "domain_data_across_components": false,
+      "caches_data": true,
+      "observability_convention": true,
+      "deploys_to_infra": false,
+      "shared_base_libs": false,
+      "is_monorepo": false,
+      "multi_platform": true,
+      "published_package": true,
+      "embedded_in_host": false,
+      "cross_repo_deps_material": false,
+      "security_arch_warranted": false,
+      "exposes_commands_or_artifacts": false
+    },
+    "resolved_by": "claude-code/claude-sonnet-5-5 (host metadata; bootstrap questionnaire)",
+    "resolved_at": "2026-10-07T04:04:09Z"
+  }
+}

package/AGENTS.md

@@ -0,0 +1,181 @@
+<!-- sdd-generated-metadata
+doc_kind: agent-entry
+generated_from: agents@0.3.0
+generated_by: claude-code
+approved_by: riag@cisco.com
+updated_at: 2026-10-07T15:08:52Z
+validation_status: pass
+-->
+
+# AI Agent Instructions
+
+Instructions for AI coding assistants working in `@webex/internal-plugin-device`, a package of the Webex JS SDK
+monorepo. The monorepo root has its own `AGENTS.md`; this file adds the package-specific rules and does not replace it.
+
+## Working Method
+
+- Read the relevant repository files before editing. Do not edit blind.
+- Understand the task and affected surfaces before writing code.
+- Prefer focused edits over rewriting whole files.
+- Do not invent commands, paths, exports, or behavior. Verify them from repository-local source.
+- Test or validate before declaring done.
+- Keep output concise. If something is uncertain, say so instead of guessing.
+
+## Canonical Repository Documentation
+
+Before changing code or documentation, start with:
+
+- [`docs/index.md`](docs/index.md) for repository documentation navigation;
+- [`docs/architecture.md`](docs/architecture.md) for repository boundaries and interactions;
+- [`docs/specs/README.md`](docs/specs/README.md) for the manifest-backed module and contract registry;
+- the affected module's manifest-routed spec, [`src/docs/README.md`](src/docs/README.md); and
+- [`docs/adr/index.md`](docs/adr/index.md) plus applicable concrete ADRs for durable decisions.
+
+Follow `.sdd/manifest.json` for each contract's publication state and canonical source. This package owns no
+HTTP API: its published surface is the npm package declared in `package.json`, and its other contracts are
+internal. The manifest remains authoritative for canonical paths and artifact decisions.
+
+## 1. Commands (Run First)
+
+Use only documented commands. Do not invent alternatives when a command is missing. Run them from the monorepo root.
+
+| Task                   | Command                                                    |
+| ---------------------- | ---------------------------------------------------------- |
+| Install dependencies   | Not defined in this package; installed by the monorepo root workspace |
+| Start dev environment  | Not applicable: a library with no process to start         |
+| Run tests              | `yarn workspace @webex/internal-plugin-device test:unit`   |
+| Run linters            | `yarn workspace @webex/internal-plugin-device test:style`  |
+| Build/release artifact | `yarn workspace @webex/internal-plugin-device build:src`   |
+| Format code            | Not defined in this package (Prettier is a dev dependency without a script) |
+
+If a required command is unknown, stop and ask for the exact command.
+
+## 2. Agent Persona and Scope
+
+You are the Webex JS SDK engineering assistant for `@webex/internal-plugin-device`.
+
+Primary outcomes:
+
+- Deliver production-safe changes with passing tests.
+- Preserve existing behavior unless a change request explicitly requires a behavior change.
+- Keep docs and configuration aligned with code changes.
+
+Definition of done:
+
+1. Requested change is implemented.
+2. Relevant tests/lint/build checks pass locally.
+3. Updated docs/config cover new behavior, including the module spec when a requirement, invariant, or failure mode changes.
+4. PR summary includes risks and rollback notes.
+
+## 3. Repository Knowledge
+
+### Tech Stack
+
+| Area             | Tooling                                         | Version                                              |
+| ---------------- | ----------------------------------------------- | ---------------------------------------------------- |
+| Language runtime | Node.js, browser                                | `>=18` (`engines` in `package.json`)                 |
+| Build tool       | `@webex/legacy-tools` (`webex-legacy-tools build`) | Workspace-pinned                                   |
+| Test framework   | Jest (unit), Mocha through Karma (integration), Sinon, Chai | Jest workspace-pinned; Sinon `^9.2.4`; Chai `^4.3.4` |
+| Lint/format      | ESLint, Prettier                                | `^8.24.0`, `^2.7.1`                                  |
+
+### Project Map
+
+- `src/`: plugin source (`device.js`, `index.js`, `config.js`, `constants.js`, `types.ts`, `ipNetworkDetector.ts`)
+- `src/features/`: feature toggle models
+- `src/interceptors/`: the `cisco-device-url` request interceptor
+- `src/docs/README.md`: the canonical module specification
+- `test/unit/spec/` and `test/integration/spec/`: unit and integration tests
+- `docs/`: package architecture, getting started, registry, and ADRs
+- `.sdd/manifest.json`: machine-readable SDD manifest; `.repo-context.json`: operational context for agents
+
+### Critical Constraints
+
+- Other SDK packages read `webex.internal.device` property and event names directly; renaming one is a breaking change.
+- Never attach `cisco-device-url` to `idbroker`, `oauth`, or `saml` requests, and never store `services` or `serviceHostMap` on the device.
+- The package is an internal plugin: semantic versioning is not strictly followed, but dependent packages in the monorepo still break on API changes.
+
+## 4. Testing Workflow
+
+Run checks in this order:
+
+1. `yarn workspace @webex/internal-plugin-device test:unit`
+2. `yarn workspace @webex/internal-plugin-device test:style`
+3. `yarn workspace @webex/internal-plugin-device test:browser` when integration behavior changes (needs provisioned Webex test users)
+
+Testing rules:
+
+- Add or update tests for every behavior change.
+- Cover failure paths and edge cases, not only happy paths.
+- Do not remove tests to make CI pass.
+
+## 5. Code Style and Patterns
+
+Coding expectations:
+
+- Follow repository style rules and static analysis output.
+- Prefer small, composable functions over large procedural blocks.
+- Make error handling explicit at system boundaries.
+- Keep public interfaces stable unless a breaking change is requested.
+- Before adding a literal path, filename, command, workflow identifier, status,
+  or other policy value, search the repository for exact and semantically
+  equivalent uses. When repeated production values represent one shared
+  contract, move them to the narrowest owning shared module or catalog as one
+  canonical named constant, enum, or type and update consumers. Keep incidental
+  similarities, one-off implementation details, and independent test fixtures
+  local.
+- Do not import a default, named, object, or namespace binding and immediately
+  re-export it. Consumers should import from the owning module; package barrels
+  should use direct named re-exports.
+- Do not write inline runtime `typeof` checks outside descriptively named guard
+  implementations. Import and reuse the owning guard instead; TypeScript
+  type-position `typeof` queries remain allowed.
+- Write Ampersand `derived` functions as methods, not arrow functions, and keep `@waitForValue('@')` on methods that need loaded persisted state.
+
+Pattern example:
+
+```text
+Preferred:
+- Validate external input close to the boundary.
+- Return typed/structured results.
+- Include actionable error messages.
+
+Avoid:
+- Passing unvalidated payloads deep into the system.
+- Swallowing exceptions or returning ambiguous null values.
+```
+
+## 6. Git Workflow
+
+- Branch naming: follow the monorepo root conventions; this package defines none of its own.
+- Commit format: conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`), as enforced by the monorepo root commit lint configuration.
+- Keep commits focused and reversible.
+- Rebase on the target branch before opening PR.
+
+PR checklist:
+
+- What changed and why.
+- Tests run and results.
+- Risk/impact areas.
+- Rollback approach.
+
+## 7. Boundaries and Escalation
+
+### Always
+
+- Prefer existing patterns over introducing new architecture.
+- Keep changes minimal for the requested scope.
+- Call out assumptions and unknowns explicitly.
+
+### Ask First
+
+- Adding new dependencies or external services.
+- Large refactors or schema migrations.
+- Security-sensitive changes (auth, encryption, secrets handling).
+- Any destructive data or infrastructure operation.
+
+### Never
+
+- Commit secrets, keys, or credentials.
+- Bypass required checks by disabling tests or linters.
+- Rewrite history on shared branches.
+- Change unrelated files "while here" without clear need.

package/dist/device.js

@@ -951,7 +951,7 @@ var Device = _webexCore.WebexPlugin.extend((_dec = (0, _webexCore.waitForValue)(
       _this10.resetLogoutTimer();
     });
   } /* eslint-enable require-jsdoc */,
-  version: "3.12.0-next.54"
+  version: "3.12.0-next.55"
 }, (0, _applyDecoratedDescriptor2.default)(_obj, "refresh", [_common.oneFlight, _dec], (0, _getOwnPropertyDescriptor.default)(_obj, "refresh"), _obj), (0, _applyDecoratedDescriptor2.default)(_obj, "register", [_dec2], (0, _getOwnPropertyDescriptor.default)(_obj, "register"), _obj), (0, _applyDecoratedDescriptor2.default)(_obj, "_registerInternal", [_common.oneFlight, _dec3], (0, _getOwnPropertyDescriptor.default)(_obj, "_registerInternal"), _obj), (0, _applyDecoratedDescriptor2.default)(_obj, "unregister", [_common.oneFlight, _dec4], (0, _getOwnPropertyDescriptor.default)(_obj, "unregister"), _obj), (0, _applyDecoratedDescriptor2.default)(_obj, "markUrlFailedAndGetNew", [_dec5], (0, _getOwnPropertyDescriptor.default)(_obj, "markUrlFailedAndGetNew"), _obj), (0, _applyDecoratedDescriptor2.default)(_obj, "initialize", [_dec6], (0, _getOwnPropertyDescriptor.default)(_obj, "initialize"), _obj), _obj));
 var _default = exports.default = Device;
 //# sourceMappingURL=device.js.map

package/dist/ipNetworkDetector.js

@@ -225,7 +225,7 @@ var IpNetworkDetector = _webexCore.WebexPlugin.extend({
       }, _callee2, null, [[2,, 4, 5]]);
     }))();
   },
-  version: "3.12.0-next.54"
+  version: "3.12.0-next.55"
 });
 var _default = exports.default = IpNetworkDetector;
 //# sourceMappingURL=ipNetworkDetector.js.map

package/docs/adr/index.md

@@ -0,0 +1,28 @@
+<!-- sdd-generated-metadata
+doc_kind: standing-doc
+generated_from: adr-index@0.3.0
+generated_by: claude-code
+approved_by: riag@cisco.com
+updated_at: 2026-10-07T15:08:52Z
+validation_status: pass
+-->
+
+# Architectural decision records
+
+Numbered, append-only records of structural decisions affecting this package
+and its documentation. Add a concrete ADR (for example, `0001-cache-policy.md`) when a decision
+is non-obvious, hard to reverse, or worth explaining to a future contributor.
+Do not edit an accepted decision in place when its outcome changes; supersede it
+with a new ADR and link both records.
+
+## Index
+
+No architectural decisions are registered yet. Decisions that the code implies but no record explains (for
+example, the cleanup-then-retry policy for excessive registrations) need their rationale confirmed by the package
+owners before an ADR is written; this generation deliberately did not invent one.
+
+Add new entries as ADRs are accepted. Keep this list in numeric order.
+
+Each ADR should state its context, decision, alternatives, consequences, and
+the condition that would cause the team to revisit it. Record the deciders,
+any superseded decision, and the constraint future changes must preserve.