@webex/common-timers 3.12.0-mobius-socket.3 → 3.12.0-next.10

package/docs/architecture.md

@@ -0,0 +1,243 @@
+---
+type: Architecture
+title: '@webex/common-timers architecture'
+description: Repository-wide boundaries, resources, interactions, dependencies, and cross-cutting architecture.
+tags: [architecture]
+---
+<!-- sdd-generated-metadata
+doc_kind: standing-doc
+generated_from: architecture@0.3.0
+generated_by: claude-code
+approved_by: pending
+updated_at: 2026-09-28T05:34:36Z
+validation_status: pass
+-->
+
+# @webex/common-timers architecture
+
+Canonical architecture for the `@webex/common-timers` package. This document owns the facts that span
+the package as a whole — what it is, what it publishes, what it depends on, and the platform and
+release boundaries it sits inside. Behavior belongs to the owning module specification and is linked,
+not repeated.
+
+Related context: [specification registry](specs/README.md) ·
+[repository agent instructions](../AGENTS.md)
+
+## Applicability
+
+| Condition ID                         | Status     | Evidence or reason                                                                                              | Owned section                       |
+| ------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `repo.owns_datastore`                | N/A        | No migrations, ORM configuration, schema file, or connection string exists                                        | Repository data and schema          |
+| `repo.holds_client_state`            | N/A        | No store or shared state model; the only state is one private field per `Timer` instance                          | Client state model                  |
+| `repo.components_interact`           | N/A        | The package is a single module with a single source file; there is no second component to interact with           | Dependency and interaction topology |
+| `repo.domain_data_across_components` | N/A        | No domain entities exist; callbacks and durations are opaque values the package never inspects                    | Object and data ownership           |
+| `repo.caches_data`                   | N/A        | No cache client, memoization, or bounded store                                                                    | Caching catalog                     |
+| `repo.observability_convention`      | N/A        | No logger, metric, trace, or audit call; the package emits nothing observable                                     | Observability patterns              |
+| `repo.deploys_to_infra`              | N/A        | No container, manifest, or cloud configuration; the package is published to a registry, not deployed              | Runtime and infrastructure          |
+| `repo.shared_base_libs`              | Applicable | Build, lint, and test behavior are inherited from workspace-internal `@webex/*-legacy` packages                   | Shared and base libraries           |
+| `repo.is_monorepo`                   | N/A        | The documented scope is one package; workspace-wide package mapping is owned outside it                           | Package map and dependencies        |
+| `repo.multi_platform`                | Applicable | The `unref` capability check, the `process` browser shim, and the browserify transform encode a Node/browser split | Platform matrix                     |
+| `repo.published_package`             | Applicable | `package.json` declares `main`, `devMain`, and `deploy:npm`                                                       | Release and versioning              |
+| `repo.embedded_in_host`              | N/A        | Consumed as a dependency; no mount contract, plugin manifest, or widget registration                              | Host integration and theming        |
+| `repo.exposes_commands_or_artifacts` | N/A        | No CLI, generator, or repository-owned command surface; the published build output is covered by Release and versioning | Commands and generated artifacts |
+| `repo.cross_repo_deps_material`      | N/A        | The package declares no runtime dependencies, so nothing external can affect its behavior or delivery             | Cross-repository topology           |
+| `repo.security_arch_warranted`       | N/A        | No identity, token, secret, encryption, or trust boundary; the posture is recorded under Cross-cutting architecture | Security architecture              |
+
+## Design overview
+
+`@webex/common-timers` exists to solve one problem for every other package in the Webex JS SDK: a
+pending timer must never be the reason a Node process refuses to exit.
+
+Node's `setTimeout` and `setInterval` return a `Timeout` object that counts toward process liveness
+until it fires or is cleared. An SDK that schedules retries, heartbeats, and batch flushes therefore
+keeps a host CLI or test run alive long after the caller's work is done. Node's answer is
+`Timeout.unref()`, and this package's answer is to make calling it unforgettable: the SDK imports
+`safeSetTimeout` and `safeSetInterval` instead of the globals, and the `unref` call is built in.
+
+That decision shapes everything else. Because browsers return a plain number with no `unref` method,
+the wrappers feature-detect the method on the returned handle rather than branching on the platform —
+so one module, one build, and no bundler shim serve both targets, at the cost of a
+`number | NodeJS.Timeout` return type that every consumer has to accept.
+
+A third export, `Timer`, sits on top. It is the one abstraction the free functions cannot express: a
+deadline a caller can push back repeatedly and then retire, with a guarded `init → running → done`
+lifecycle that throws rather than silently ignoring an invalid call. It arms itself through
+`safeSetTimeout`, so a managed timer inherits the same process-exit safety.
+
+The package is 117 lines in one file with zero runtime dependencies. Its architectural weight is
+entirely in what it promises to the eleven workspace packages that consume it, not in its internal
+structure.
+
+## Resource inventory and responsibilities
+
+| Resource               | Kind    | Responsibility                                                                                          | Owner                      | Source         | Detailed specification |
+| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------- | -------------------------- | -------------- | ---------------------- |
+| `@webex/common-timers` | Package | Publish the SDK's timer vocabulary to npm and to the surrounding workspace                              | Cisco Webex for Developers | `package.json` | `src/docs/README.md`   |
+| `src`                  | Module  | The timer primitives themselves: both scheduling wrappers, the `unref` capability check, and the `Timer` lifecycle | Cisco Webex for Developers | `src/index.ts` | [`src/docs/README.md`](../src/docs/README.md) |
+
+## Interaction and execution flows
+
+The package has no internal interactions to diagram — one module, one file. The architecturally
+meaningful flow is the one that crosses its boundary: a consuming SDK package calls in, the module
+calls the host runtime, and the host calls the consumer's callback back directly.
+
+```mermaid
+flowchart LR
+  Consumer[Consuming SDK package] -->|import| Entry["src/index.ts"]
+  Entry -->|setTimeout / setInterval| Host[Host timer API]
+  Entry -->|unref when supported| Host
+  Host -.->|callback on the event loop| Consumer
+  Consumer -->|clearTimeout / clearInterval| Host
+```
+
+| From                  | To                    | Interaction or transport         | Purpose                                                                       | Failure or compatibility behavior                                                                            |
+| --------------------- | --------------------- | -------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Consuming SDK package | `src`                 | Static import, synchronous call  | Schedule deferred or repeating work, or bound a request with a resettable deadline | `Timer` throws synchronously on an invalid lifecycle call; the free functions have no rejected path          |
+| `src`                 | Host timer API        | Direct call to the runtime global | Create the timer and release it from process liveness                          | Platform errors propagate unchanged. A missing `unref` is skipped silently, leaving the platform default      |
+| Host timer API        | Consuming SDK package | Event-loop callback              | Deliver the scheduled callback                                                 | A Node process may exit before the delay elapses, in which case the callback is never invoked at all          |
+| Consuming SDK package | Host timer API        | Direct call to the runtime global | Cancel a timer using the returned handle                                       | The package exports no clear function; cancellation uses the platform's own `clearTimeout` / `clearInterval`  |
+
+## Dependency topology
+
+| Dependency                              | Type     | Used by | Purpose                                                                   | Version, failure, or fallback policy                                                                       |
+| --------------------------------------- | -------- | ------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Host timer API                          | External | `src`   | `setTimeout`, `setInterval`, and `clearTimeout` — the primitives being wrapped | No fallback and no polyfill. Whatever the runtime throws propagates to the caller unchanged                 |
+| `Timeout.unref()` (Node-only extension) | External | `src`   | Release a pending timer from process liveness                             | Feature-detected on the handle. Absent in browsers, where the branch is skipped and the platform default applies |
+| `@webex/babel-config-legacy`            | Internal | build   | Transpilation configuration                                               | `workspace:*`; development only, never shipped in the published artifact                                    |
+| `@webex/eslint-config-legacy`           | Internal | lint    | Lint rules                                                                | `workspace:*`; development only                                                                             |
+| `@webex/jest-config-legacy`             | Internal | test    | Unit-test configuration                                                   | `workspace:*`; development only                                                                             |
+| `@webex/legacy-tools`                   | Internal | build   | The `webex-legacy-tools` build and test runner                            | `workspace:*`; development only                                                                             |
+
+There are **no runtime dependencies**: `package.json` declares only `devDependencies`. That removes
+every cycle, ordering constraint, and third-party single point of failure from this package — the
+only thing it can depend on at runtime is the host itself. Exact versions live in
+[`package.json`](../package.json).
+
+## Public and consumer surfaces
+
+| Surface                | Type | Owner | Consumers                                                                                                                                                                  | Compatibility policy                                                                                                                                    | Source         |
+| ---------------------- | ---- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `common-timers-sdk`    | SDK  | `src` | Declared by `internal-plugin-mercury`, `internal-plugin-metrics`, `internal-plugin-device`, `internal-plugin-encryption`, `internal-plugin-avatar`, `internal-plugin-dss`, `internal-plugin-ai-assistant`, `internal-plugin-scheduler`, `webex-core`, and `calling`; additionally imported, without being declared, by `plugin-meetings` | Published npm surface: `safeSetTimeout`, `safeSetInterval`, and `Timer`. Stable under the workspace's shared semantic version; the wrapper signatures track the platform's own | `package.json` |
+
+`common-timers-sdk` is the package's only contract. Its canonical native source is the package entry
+point declared by `main` and `devMain` in [`package.json`](../package.json); per-export detail,
+including the parameter and return types, lives in the owning module specification's `Public surface`
+and `Export stability` sections at [`src/docs/README.md`](../src/docs/README.md). This page indexes
+the contract; it does not restate the declarations.
+
+The declared and importing consumer sets differ in both directions, which matters for impact
+analysis: `internal-plugin-scheduler` declares the dependency without importing it, and
+`plugin-meetings` imports it without declaring it. A dependency-graph query over `package.json`
+files alone therefore both over- and under-states the blast radius of a surface change. The module
+specification records the per-export breakdown.
+
+The package consumes one external contract, `host-timer-api` — the runtime's own
+`setTimeout`/`setInterval`/`clearTimeout` plus the Node `Timeout.unref()` extension. It is external
+and unversioned by this repository; its consumption is recorded in the module spec's `Dependencies`.
+
+## Cross-cutting architecture
+
+### Security
+
+- **Trust boundaries and identity flow:** none. The package has no identity, no authentication, and
+  no trust boundary. It never reads configuration, never touches the network, and never inspects the
+  callback or duration a caller passes it.
+- **Sensitive surfaces and data classes:** none. No data of any classification transits the package;
+  arguments are forwarded to the host scheduler and never stored, logged, or serialized.
+- **Encryption and secret boundaries:** not applicable. Nothing is persisted or transmitted.
+
+The security-relevant property of this package is a liveness one, not a confidentiality one: because
+every timer is unref-ed, the package can cause scheduled work to be silently dropped at process exit.
+Consumers that require a callback to run before shutdown must hold the process open themselves.
+
+### Observability and operations
+
+- **Logging and correlation:** none. The package emits no log line, and deliberately takes no logger
+  dependency — a timer primitive called from ten packages would produce noise with no correlation
+  context of its own. Consumers log around their own timer usage.
+- **Metrics, traces, and audit signals:** none emitted or consumed.
+- **Ownership and operational entry points:** the package is maintained by Cisco Webex for Developers
+  as part of the Webex JS SDK workspace; it has no dashboard, alert, or runbook of its own because it
+  has no runtime deployment. Failures surface inside the consuming package.
+
+### Quality attributes
+
+The measurable expectations that fit a dependency-free utility package of this size:
+
+| Attribute                 | Expectation                                                                                                               | Evidence                                    |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| Footprint                 | Zero runtime dependencies; the published artifact is one transpiled module                                                | `package.json`                              |
+| Platform compatibility    | The same build runs on Node `>=18` and in a browser, with no conditional export or bundler shim                            | `package.json`, `src/index.ts`, `process`   |
+| Process-exit safety       | No timer created through this package extends process lifetime                                                            | `src/index.ts`                              |
+| Lifecycle correctness     | Every invalid `Timer` transition is rejected rather than ignored; all six rejection branches are covered by unit tests     | `test/unit/spec/index.ts`                   |
+| Process-exit verification | **Not verified by test.** No assertion covers the `unref` contract on either platform branch       | `src/index.ts` (code reading only)          |
+| Test verification         | 13 unit cases in one suite, all passing. No coverage threshold gates the package — coverage collection is disabled in its jest config | `test/unit/spec/index.ts`, `jest.config.js` |
+
+Process-exit safety is the attribute that most needs proving and is the one still unproven: the
+`unref` calls in `src/index.ts` carry no test, so removing them would not turn the suite red. The
+attribute is supported by code reading alone. Lifecycle correctness, by contrast, is thoroughly
+covered. Per-requirement evidence and the full list of coverage gaps are recorded in the module
+specification's `Verification` section.
+
+## Shared and base libraries
+
+Every build, lint, and test behavior in this package is inherited. The package contributes three
+two-line configuration files that do nothing but re-export the shared configuration.
+
+| Library                       | Inherited responsibility                                                       | Consumers                   | Version floor | Compatibility rule                                                                        |
+| ----------------------------- | -------------------------------------------------------------------------------- | --------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
+| `@webex/babel-config-legacy`  | Transpilation targets and plugins, re-exported verbatim by `babel.config.js`   | Build                       | `workspace:*` | Pinned to the workspace; a change to the shared config changes this package's output       |
+| `@webex/eslint-config-legacy` | All lint rules, extended by `.eslintrc.js` with `root: true` and nothing else   | `test:style`                | `workspace:*` | Pinned to the workspace; this package adds no local rule or override                       |
+| `@webex/jest-config-legacy`   | Unit-test runner configuration, re-exported verbatim by `jest.config.js`        | `test:unit`                 | `workspace:*` | Pinned to the workspace. It sets `collectCoverage: false`, which is why no gate applies here |
+| `@webex/legacy-tools`         | The `webex-legacy-tools` build and test CLI invoked by the package scripts      | `build:src`, `test:unit`    | `workspace:*` | Pinned to the workspace; command flags are owned there, not here                           |
+
+The practical consequence for a contributor: there is no package-local knob. Changing how this
+package builds, lints, or tests means changing the shared workspace configuration.
+
+## Platform matrix
+
+The package targets Node and the browser from one source file and one build. The split is a single
+runtime capability check, not a build-time branch.
+
+| Platform | Shared versus platform-specific boundary                                                                                          | Entry or build                                                           | Support and compatibility constraints                                                                                             |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Node     | Fully shared. The handle is a `Timeout` object exposing `unref`, so the capability check succeeds and the timer is released from process liveness | `dist/index.js` via `main`, built by `build:src`                         | Requires Node `>=18` per `engines`. Scheduled callbacks may be dropped at process exit — that is the intended behavior             |
+| Browser  | Fully shared. The handle is a number with no `unref`, so the check fails and the platform default applies                         | Same module; the browserify transform resolves the `process` shim to `{browser: true}` | No separate bundle, no `browser` field in `package.json`, and no polyfill. Behavior degrades to plain `setTimeout`/`setInterval` |
+
+Because the two platforms return different handle types, the exported return type is the union
+`number | NodeJS.Timeout`. That union is the visible cost of the single-build decision, and it is
+part of the published contract rather than an implementation detail.
+
+## Release and versioning
+
+| Artifact               | Publish target | Versioning rule                                                                                                 | Deprecation window                                                                      | Changelog or migration obligation                                                              |
+| ---------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `@webex/common-timers` | npm            | Published by `deploy:npm`. Version numbers are assigned by the workspace release pipeline, not declared in this package's `package.json` | Governed by the workspace release process; the package declares none of its own         | Changelog generation is owned at the workspace root. This package ships no `CHANGELOG.md`      |
+
+The published artifact is `dist/index.js`, produced by `build:src`. In-workspace consumers resolve
+`devMain` (`src/index.ts`) instead, so a change to the source is visible to sibling packages without
+a publish. A breaking change to any of the three exports is a breaking change for eleven workspace
+packages plus external npm consumers; the module specification's `Export stability` section records
+what specifically is promised, including that the `Timer` rejection message wording is asserted by
+the unit suite.
+
+## Domain language
+
+| Term             | Repository-specific meaning                                                                                                                     | Authoritative source |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| unref            | Asking a Node timer handle to stop counting toward process liveness, so a pending timer cannot prevent the process from exiting                 | `src/index.ts`       |
+| safe             | In `safeSetTimeout` / `safeSetInterval`, specifically "safe against wedging a process open" — it implies nothing about error handling or types  | `README.md`          |
+| handle           | The value the host scheduler returns: a `Timeout` object in Node, a number in a browser. The package returns it unchanged after unref-ing it     | `src/index.ts`       |
+| arm              | Move a `Timer` from `init` to `running` by scheduling its callback. Only `start()` arms a timer                                                 | `src/index.ts`       |
+| reset            | Clear a running timer and re-arm it for the **full** original timeout. It is an idle deadline, not a pause or a resume                          | `src/index.ts`       |
+| done             | The terminal `Timer` state, reached by either expiry or cancellation. It is not recoverable and the two causes are indistinguishable            | `src/index.ts`       |
+
+## References and maintenance
+
+- Decisions: [adr/](adr/)
+- Instantiated specifications and routing: [specs/README.md](specs/README.md)
+- Module specification: [`src/docs/README.md`](../src/docs/README.md)
+- Getting started: [getting-started.md](getting-started.md)
+- Update this document in the same change that alters the package's published surface, its
+  dependency posture, its platform support, or its release boundary. A change confined to timer
+  behavior belongs in the module specification instead.

package/docs/getting-started.md

@@ -0,0 +1,121 @@
+---
+type: Getting Started
+title: Getting started
+description: Local setup, build, run, and test routing for @webex/common-timers.
+tags: [onboarding]
+---
+<!-- sdd-generated-metadata
+doc_kind: standing-doc
+generated_from: getting-started@0.3.0
+generated_by: claude-code
+approved_by: pending
+updated_at: 2026-09-28T05:34:36Z
+validation_status: pass
+-->
+
+# Getting started
+
+Onboarding for **`@webex/common-timers`**. The package is one of many in the Webex JS SDK yarn
+workspace, so every command below is run from the workspace root and targets this package by name.
+
+## Prerequisites
+
+| Tool or access | Version or requirement                                                                                                                                                             |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Node.js        | `package.json` declares the package floor as `>=18`. The surrounding workspace pins a newer Node through its own `.nvmrc` and contributor instructions, so match the workspace when working in-tree |
+| Yarn           | The workspace ships its own Yarn release and resolves it automatically; do not install Yarn separately                                                                              |
+| Registry, VPN, or account access | N/A. The package has no runtime dependencies and resolves nothing from a private registry                                                                          |
+
+## Install
+
+```bash
+yarn install
+```
+
+Run `yarn install` once at the Webex JS SDK workspace root. It installs every package in the
+workspace, including this one; there is no package-local install step.
+
+Cloning the workspace is owned at the workspace root, not by this package, so no clone command is
+recorded here — follow the root repository's own instructions to obtain a checkout first.
+
+## Build
+
+```bash
+yarn workspace @webex/common-timers build:src
+```
+
+This runs `webex-legacy-tools build` over `src/` and writes the transpiled module plus type
+declarations and source maps to `dist/`, which is what `main` points at for published consumers.
+`yarn workspace @webex/common-timers build` is an alias for the same thing.
+
+## Run
+
+```bash
+# N/A — this package has no runnable entry point.
+yarn workspace @webex/common-timers test:unit
+```
+
+There is nothing to start. The package is a library with no CLI, server, or runtime entry point —
+`package.json` declares no `bin` and no `start` script. The closest thing to running it is executing
+its unit suite, or importing it from a sibling workspace package, which resolves `devMain`
+(`src/index.ts`) directly without a build.
+
+## Tests
+
+```bash
+yarn workspace @webex/common-timers test:unit
+```
+
+The package declares exactly one test tier. `package.json` also declares an aggregate `test` script,
+but it chains `test:integration` and `test:browser`, neither of which this package defines — so
+`yarn workspace @webex/common-timers test` cannot succeed. Use the individual commands.
+
+| Tier | Command                                            | Test location             | Framework | External dependencies |
+| ---- | -------------------------------------------------- | ------------------------- | --------- | --------------------- |
+| Unit | `yarn workspace @webex/common-timers test:unit`    | `test/unit/spec/index.ts` | jest      | None                  |
+
+Lint runs separately:
+
+```bash
+yarn workspace @webex/common-timers test:style
+```
+
+- Coverage or quality gate: N/A. The resolved `jest.config.js` sets `collectCoverage: false` and
+  declares no threshold, and the package has no `test:coverage` script for the workspace CI coverage
+  job to pick up. Verified with the package owner during onboarding.
+- Enforcement source: `jest.config.js`, which re-exports the shared `@webex/jest-config-legacy`
+  configuration
+- Test environment or QA dependencies: none. The suite runs entirely in-process against sinon fake
+  timers
+
+## Configuration and secrets
+
+- Required configuration: none. The package reads no environment variable, config file, or remote
+  setting.
+- Secret source: N/A — the package handles no credentials.
+- Package or artifact access: N/A — no runtime dependencies and no private registry.
+- Required neighboring repositories or workspace layout: the package must be built and tested from
+  inside the Webex JS SDK workspace, because its build, lint, and test configuration are all
+  `workspace:*` dependencies (`@webex/legacy-tools`, `@webex/jest-config-legacy`,
+  `@webex/eslint-config-legacy`, `@webex/babel-config-legacy`).
+- Platform, simulator, device, or SDK setup: N/A.
+- Never commit credentials or copy production secrets into a local config.
+
+## First-run verification
+
+1. Run `yarn install` at the workspace root.
+2. Run `yarn workspace @webex/common-timers test:unit`.
+3. Run `yarn workspace @webex/common-timers build:src` and confirm `dist/index.js` exists.
+
+Expected result: the unit suite reports **13 passed, 13 total** from the single suite at
+`test/unit/spec/index.ts`, covering `safeSetTimeout` callback delivery, `safeSetInterval` repetition,
+and the three `Timer` methods with all six rejected transitions. The `unref` contract is not
+asserted anywhere; see the module spec's `Verification` section. The build writes `dist/`.
+
+## Next steps
+
+- [Repository architecture](architecture.md)
+- [Specification registry](specs/README.md)
+- [Module specification](../src/docs/README.md) — the behavior contract, state machine, and known
+  test gaps
+- [Documentation index](index.md)

package/docs/index.md

@@ -0,0 +1,50 @@
+---
+okf_version: '0.1'
+---
+<!-- sdd-generated-metadata
+doc_kind: standing-doc
+generated_from: docs-index@0.3.0
+generated_by: claude-code
+approved_by: pending
+updated_at: 2026-09-28T05:34:36Z
+validation_status: pass
+-->
+
+# @webex/common-timers documentation
+
+Doc map for developers and agents working on the timer primitives the Webex JS SDK schedules all of
+its deferred work through.
+
+## Start here
+
+- [Getting started](getting-started.md) — prerequisites, build, and the test router
+- [Repository architecture](architecture.md) — what the package publishes, what it depends on, and
+  the platform and release boundaries it sits inside
+
+There is no service specification and no API specification for this package: it is a published
+library with no deployable runtime and no HTTP surface. Both omissions are recorded in
+`.sdd/manifest.json` under `layout.artifact_decisions`.
+
+## Decisions
+
+- [adr/](adr/) — architectural decision records. None are registered yet; the decisions that shape
+  the current design are recorded in the module specification's `Key design trade-off` section.
+
+## Specifications and contracts
+
+- [architecture.md](architecture.md) — canonical package-wide architecture and the contract index
+- [specs/README.md](specs/README.md) — module and specification registry
+- [`src/docs/README.md`](../src/docs/README.md) — the owning specification beside the module's code:
+  public surface, requirements, state machine, failure modes, and verification
+- [adr/](adr/) — concrete architectural decisions; the blank ADR template stays under `.sdd/`
+
+The package's one contract, `common-timers-sdk`, is a published npm package surface. Its native
+source is the entry point declared by `main` and `devMain` in [`package.json`](../package.json), and
+the exact declarations live in [`src/index.ts`](../src/index.ts). The architecture page indexes that
+contract and the module specification details it; neither copies the declarations into Markdown.
+
+## Related repository resources
+
+- [`README.md`](../README.md) — the package's npm-facing readme, covering install and basic usage
+- Contribution guidelines, changelog generation, and the release pipeline are owned at the Webex JS
+  SDK workspace root, not in this package

package/docs/specs/README.md

@@ -0,0 +1,86 @@
+---
+type: Reference
+title: Specification registry
+description: Canonical specification registry and change-routing guide.
+tags: [specifications, registry]
+---
+<!-- sdd-generated-metadata
+doc_kind: standing-doc
+generated_from: spec-index@0.3.0
+generated_by: claude-code
+approved_by: pending
+updated_at: 2026-09-28T05:34:36Z
+validation_status: pass
+-->
+
+# Specification registry
+
+Use this page to find the canonical architecture for `@webex/common-timers` and every instantiated
+module specification plus native contract. Technical facts stay in one owning document; this page is
+navigation, ownership, status, and change/test routing only.
+
+Start with the [repository architecture](../architecture.md). There is no service specification: the
+package is a published library, not a deployable service.
+
+## Document roles
+
+| Document                                       | Canonical ownership                                                                                                  |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| [Repository architecture](../architecture.md)  | Package boundaries, resource inventory, interactions, dependency topology, and cross-cutting architecture            |
+| Service specification                          | N/A — not generated. The package has no deployable runtime, so no service or operating contract exists                |
+| Module specifications                          | Stable behavior and design at each module's `docs/README.md`, routed by `.sdd/manifest.json`                          |
+| [ADR](../adr/)                                 | A durable decision, its deciders, rationale, consequences, and supersession lineage. None are registered yet         |
+
+## Instantiated specification registry
+
+| Resource               | Role         | Canonical path         | Owner                      | Status | Last verified |
+| ---------------------- | ------------ | ---------------------- | -------------------------- | ------ | ------------- |
+| `@webex/common-timers` | Architecture | `docs/architecture.md` | Cisco Webex for Developers | Active | 2026-09-28    |
+| `src`                  | Module       | `src/docs/README.md`   | Cisco Webex for Developers | Active | 2026-09-28    |
+| `common-timers-sdk`    | Contract     | `package.json`         | Cisco Webex for Developers | Active | 2026-09-28    |
+
+### Module registry
+
+One row per module in `.sdd/manifest.json`, which stays authoritative; this table is its
+human-readable mirror and the reconciliation surface for `check_spec_index.py`.
+
+| Module | Responsibility | Manifest coverage state | Start here |
+| --- | --- | --- | --- |
+| `src/` | Timer primitives that never hold a Node process open: unref-ing wrappers over `setTimeout` and `setInterval`, plus the guarded `Timer` lifecycle | Partial | `src/docs/README.md` |
+
+Generator-side field measurement for `src` is complete: 100% (14 of 14 mandatory fields) assessed
+2026-09-24, with critical field coverage at 9 of 9. The score, date, and evidence summary are
+recorded in the module specification's `Coverage score` metadata row and in `.sdd/manifest.json`.
+
+Two gates still hold promotion open. This module has no characterization baseline, and the `unref`
+requirements (`MOD-002`, `MOD-004`, `MOD-012`) together with the re-entrancy requirement (`MOD-009`)
+have no automated evidence; the sole test file, `test/unit/spec/index.ts`, is pre-existing and covers
+the `Timer` lifecycle rather than the `unref` contract. Independent validation (validator `codex`,
+2026-09-24) returned blocked across two runs, raising three findings in total — consumer-inventory
+drift, an onboarding command with no manifest entry, and evidence-column anchors that were not
+repository file paths. All three were repaired and the third run returned pass-with-warnings. A later
+run assessed a test suite that has since been withdrawn from this change, so that result is stale.
+`src` stays `Partial` until the missing assertions and a characterization baseline exist and a fresh
+validation covers them.
+
+## Change and verification routing
+
+| Change affects                                                | Load and update                                                                                       | Verification route                                                             |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Package boundaries, dependency posture, platform support, or release | `docs/architecture.md`, and a new ADR under `docs/adr/` when the decision is durable              | `yarn workspace @webex/common-timers build:src` plus the affected module spec  |
+| Timer behavior, the `Timer` lifecycle, or a thrown message    | `src/docs/README.md` — `Requirements`, `State machine`, `Caller-visible failure modes`, `Verification` | `yarn workspace @webex/common-timers test:unit`                                |
+| The exported surface or its types                             | `src/docs/README.md` — `Public surface` and `Export stability` — plus the architecture contract index | `yarn workspace @webex/common-timers build:src` and every dependent package's unit suite |
+| Build, lint, or test configuration                            | `docs/getting-started.md` and the architecture `Shared and base libraries` section                    | `yarn workspace @webex/common-timers test:style` and `test:unit`               |
+
+## Module and contract registration
+
+The module specification is generated at the exact `modules[].canonical_spec` path recorded in
+`.sdd/manifest.json` — `src/docs/README.md`. Every module and submodule is registered in the Module
+registry above in manifest tree order; `src` has no submodules.
+
+`common-timers-sdk` is the package's only contract: a published SDK/package surface whose canonical
+native source is the entry point declared by `main` and `devMain` in `package.json`, with the exact
+declarations in `src/index.ts`. Published package surfaces retain their ecosystem-native API source
+and do not require OpenAPI, and the package serves no HTTP routes, so `api-specs/openapi.yaml` is
+omitted. The module also consumes one external contract, `host-timer-api`, the host runtime's timer
+API. This page provides navigation and ownership rather than a copied contract.

package/package.json

@@ -32,12 +32,12 @@
     "@webex/eslint-config-legacy": "0.0.0",
     "@webex/jest-config-legacy": "0.0.0",
     "@webex/legacy-tools": "0.0.0",
-    "@webex/test-helper-chai": "3.12.0-mobius-socket.3",
-    "@webex/test-helper-mocha": "3.12.0-mobius-socket.3",
-    "@webex/test-helper-mock-webex": "3.12.0-mobius-socket.3",
-    "@webex/test-helper-test-users": "3.12.0-mobius-socket.3",
+    "@webex/test-helper-chai": "3.12.0-next.9",
+    "@webex/test-helper-mocha": "3.12.0-next.9",
+    "@webex/test-helper-mock-webex": "3.12.0-next.9",
+    "@webex/test-helper-test-users": "3.12.0-next.9",
     "eslint": "^8.24.0",
     "prettier": "^2.7.1"
   },
-  "version": "3.12.0-mobius-socket.3"
+  "version": "3.12.0-next.10"
 }