@astrale-os/sdk 0.4.12 → 0.4.13

package/src/linter/analyze.ts

@@ -0,0 +1,17 @@
+import type { LintDiagnostic } from './diagnostic.js'
+import type { DomainProject } from './project.js'
+import type { AnalyzerRule } from './rules/project-rule.js'
+
+import { coreIsPure } from './rules/core-is-pure.js'
+import { oneRemoteDefinitionPerFile } from './rules/one-remote-definition-per-file.js'
+import { thinSchemaCompositionRoot } from './rules/thin-schema-composition-root.js'
+
+export const analyzerRules: readonly AnalyzerRule[] = [
+  thinSchemaCompositionRoot,
+  oneRemoteDefinitionPerFile,
+  coreIsPure,
+]
+
+export function analyzeProject(project: DomainProject): LintDiagnostic[] {
+  return analyzerRules.flatMap((rule) => rule.analyze(project))
+}

package/src/linter/diagnostic.ts

@@ -0,0 +1,68 @@
+import type { RuleOwner } from './rules/catalog.js'
+
+export type DiagnosticSeverity = 'error' | 'warning'
+
+export type DiagnosticLocation = {
+  path: string
+  line: number
+  column: number
+  offset?: number
+  length?: number
+}
+
+export type LintDiagnostic = {
+  id: string
+  severity: DiagnosticSeverity
+  message: string
+  help?: string
+  url?: string
+  owner: RuleOwner | 'generic'
+  location?: DiagnosticLocation
+}
+
+export type LintResult = {
+  root: string
+  diagnostics: LintDiagnostic[]
+  files: number
+  durationMs: number
+  exitCode: 0 | 1
+}
+
+export class LinterToolError extends Error {
+  readonly exitCode = 2
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'LinterToolError'
+  }
+}
+
+export function compareDiagnostics(a: LintDiagnostic, b: LintDiagnostic): number {
+  return (
+    (a.location?.path ?? '').localeCompare(b.location?.path ?? '') ||
+    (a.location?.line ?? 0) - (b.location?.line ?? 0) ||
+    (a.location?.column ?? 0) - (b.location?.column ?? 0) ||
+    a.id.localeCompare(b.id) ||
+    a.message.localeCompare(b.message)
+  )
+}
+
+export function dedupeDiagnostics(diagnostics: readonly LintDiagnostic[]): LintDiagnostic[] {
+  const seen = new Set<string>()
+  const result: LintDiagnostic[] = []
+  for (const diagnostic of diagnostics) {
+    const location = diagnostic.location
+    const key = [
+      diagnostic.id,
+      location?.path ?? '',
+      location?.line ?? 0,
+      location?.column ?? 0,
+      location?.length ?? 0,
+      diagnostic.message,
+    ].join(':')
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(diagnostic)
+  }
+  return result.sort(compareDiagnostics)
+}

package/src/linter/docs/DIAGNOSTICS.md

@@ -0,0 +1,47 @@
+# Diagnostics
+
+Every Astrale diagnostic uses the engine-neutral `LintDiagnostic` model and contains:
+
+- A stable `astrale/<slug>` identifier.
+- `error` or `warning` severity.
+- A message describing the violated invariant.
+- Remediation and a documentation URL when available.
+- A normalized source location when one exists.
+- The policy owner: `sdk`, `oxlint`, or `analyzer`.
+
+Messages describe domain policy rather than AST or analyzer implementation details. Engine changes must
+not rename identifiers, suppressions, or output fields.
+
+## Output
+
+Stylish output is intended for people. JSON output preserves the complete `LintResult` for automation.
+Diagnostics are sorted by path, position, identifier, and message. Duplicate reports with the same
+identifier and source span are collapsed because dual ownership is a tooling defect.
+
+Exit codes are part of the contract:
+
+- `0`: no enabled error remains.
+- `1`: policy diagnostics failed the run.
+- `2`: configuration, dependency resolution, or an underlying tool failed.
+
+Project preflight failures are tool errors, not suppressible policy diagnostics. Their messages must
+name the conflicting package or tool and preserve the original cause.
+
+## Suppressions
+
+Astrale rules share one exact, engine-neutral suppression syntax:
+
+```ts
+// astrale-disable-next-line astrale/raw-path-only-at-boundary -- provider cache key requires a string
+const key = node.path.raw
+```
+
+A suppression must:
+
+- Name exact rule identifiers.
+- Include a non-empty reason after `--`.
+- Apply only to the following line.
+- Continue to work if rule ownership moves between Oxlint and the analyzer.
+
+Generic Oxlint rules continue to use Oxlint suppression syntax. Suppressions are exceptional evidence,
+not compensation for an ambiguous or noisy rule.

package/src/linter/docs/JUDGMENT.md

@@ -0,0 +1,81 @@
+# Static-analysis Judgment
+
+Not every valuable Astrale practice is a static rule. The linter must be honest about what it cannot
+prove.
+
+## False-positive budget
+
+The burden of proof belongs to automation, not to the code author. If a rule cannot distinguish valid
+code from a violation without inferring intent, its default disposition is `guidance` or `research`,
+not `warning`.
+
+Before implementing a rule, ask:
+
+- Is the violation represented by syntax, resolved symbols, types, compiled schema, or an explicit
+  project contract?
+- Can every common valid alternative be represented without a suppression?
+- Does the diagnostic prevent a concrete failure often enough to justify its maintenance and review
+  cost?
+- Would a narrower rule capture the mechanically decidable part without claiming the broader design
+  judgment?
+
+The existence of a possible AST heuristic is not evidence that a rule should exist. Severity does not
+solve ambiguity, and a local disable comment does not make systematic false positives acceptable.
+
+## Keep in knowledge and review
+
+The following require domain or product judgment:
+
+- Whether bounded-context names and ownership reflect the business correctly.
+- Which context semantically owns a cross-context edge.
+- Whether a generic relation should instead be assignment, tagging, blocking, duplication, hierarchy,
+  or mention behavior.
+- Whether an authorization check targets the correct resource and permission.
+- Whether an intentionally open callable is appropriate.
+- Whether deletion should cascade, reject, preserve, archive, or detach related data.
+- Whether import conflict, identity, partial-failure, and idempotency semantics are adequate.
+- Whether a set of writes forms one business invariant.
+- Whether a query projects every fact required by the use case.
+- Whether a fresh read is actually required after receiving hydrated data.
+- Whether a helper legitimately owns its own durable step.
+- Whether UI vocabulary, hierarchy, and interaction design are domain-first and high quality.
+- Whether a feature should exist at all.
+
+These topics may have simulations, review checklists, or evidence collectors. They must not become
+static diagnostics based on filenames or keywords.
+
+The registry keeps these ideas with an explicit `guidance` disposition and rationale. This is a design
+record, not an implementation backlog. A narrower replacement may be proposed later under its own
+detection contract.
+
+## Heuristic promotion
+
+A heuristic may begin as an opt-in warning when it provides useful evidence, but its message must say
+what was observed rather than claim intent.
+
+For example:
+
+```text
+Observed 101 get() calls after one children() page in scenario delete-large-issue.
+```
+
+is valid evidence. The following overclaims:
+
+```text
+Your query architecture is wrong.
+```
+
+Promotion from warning to error requires repeated evidence across golden domains, a deterministic
+contract, and documented valid exceptions.
+
+Before a heuristic becomes even an opt-in warning, it must first move from `research` to `implement`.
+Report-only prototypes may collect evidence, but they must not appear as ordinary project diagnostics.
+
+## Knowledge relationship
+
+Every accepted rule links to knowledge that explains why it exists. Knowledge entries may reference
+the semantic identifier, but the registry is authoritative for automation disposition and lifecycle.
+Executable owner, severity, and detection behavior apply only after an `implement` entry is accepted.
+
+Agent skills should instruct agents to run the native project commands and interpret diagnostics. They
+should not duplicate the entire rule catalog in prose.

package/src/linter/docs/PRINCIPLES.md

@@ -0,0 +1,97 @@
+# Linter Principles
+
+## Outcome
+
+An Astrale domain should naturally compile, lint, and test toward the preferred architecture. Agents
+and humans should not need to memorize a long style guide before receiving precise feedback.
+
+Knowledge remains responsible for rationale, examples, and judgment. Mechanically decidable policy
+belongs in executable tooling.
+
+## Enforcement order
+
+For every proposed convention, choose the earliest static layer that can enforce it correctly:
+
+1. **SDK** uses its API, TypeScript types, schema compilation, and runtime contracts to reject invalid
+   states directly.
+2. **Oxlint** reports file-local syntax, scope, or control-flow violations.
+3. **Astrale analyzer** reports cross-file, import-graph, schema-aware, or project-shape violations.
+A later static layer must not duplicate a diagnostic already owned reliably by an earlier layer. If
+none can decide the convention without guessing, keep it in tests, review, or knowledge rather than
+weakening the linter.
+
+## Product principles
+
+### One native workflow
+
+Authors run ordinary package scripts. They do not assemble Oxlint plugins, TypeScript parser services,
+schema inspectors, or analyzer configuration themselves.
+
+### Prevent before reporting
+
+If an SDK signature can require `authorize`, a linter should not be the primary enforcement mechanism.
+If a complete schema-derived handler map can be expressed as a TypeScript type, a filesystem scanner
+should not guess whether it is complete.
+
+### High signal
+
+The default decision is not to automate. A rule earns implementation only when the linter can identify
+the prohibited state and its legitimate exceptions from machine-visible evidence. Even a useful
+principle should remain guidance when detection depends on guessing intent, ownership, or architectural
+quality.
+
+An error-level rule must have a deterministic detection contract and a very low false-positive rate.
+Warnings are held to the same honesty standard: lower severity does not make recurring false positives
+acceptable. Suppressions are an escape hatch for exceptional code, not compensation for a vague rule.
+
+### Stable diagnostics, replaceable engines
+
+Accepted `astrale/<slug>` identifiers are Astrale contracts. Oxlint, a TypeScript project service, or
+any future engine is an implementation detail. Changing engines must not rename accepted rules,
+suppressions, or CI output.
+
+### Strict defaults, narrow exceptions
+
+New domains receive the strict preset. Configuration exists to describe real domain structure or a
+documented exception, not to recreate an arbitrary lint stack. Suppressions are local, reasoned, and
+auditable.
+
+### Safe fixes only
+
+`pnpm lint:fix` may apply transformations that preserve behavior and intent. Moving a declaration into
+a guessed bounded context, inventing an authorization target, or grouping mutations automatically is
+not a safe fix.
+
+### Measured speed
+
+The fast path must remain interactive. New engines or rules are admitted only with cold, warm, and
+changed-file measurements against representative domains.
+
+## Rule admission bar
+
+A proposed rule may become `accepted` only when all of the following are true:
+
+- The prohibited behavior has a concrete failure mode.
+- The preferred behavior is stable across more than one domain.
+- The primary owner is exactly one of `sdk`, `oxlint`, or `analyzer`.
+- Valid and invalid examples can be stated without relying on taste.
+- Detection does not require guessing business intent.
+- Representative legitimate alternatives do not trigger.
+- Every documented exception is either machine-visible or explicitly outside the rule's scope.
+- The expected prevention value exceeds the cost of review, suppression, maintenance, and lost trust
+  from false positives.
+- The diagnostic identifies a useful source location and remediation.
+- Suppression semantics are defined.
+- Runtime and maintenance cost are measured.
+
+## Non-goals
+
+The linter does not:
+
+- Build a new JavaScript or TypeScript parser, formatter, or compiler.
+- Replace `tsgo`, Oxlint, Vitest, schema compilation, or live domain verification.
+- Infer the correct business bounded context from vocabulary alone.
+- Prove that an authorization target expresses the intended business policy.
+- Grade visual design quality or domain language by keyword.
+- Promise zero migration work for arbitrary repositories that were not scaffolded with the system.
+- Turn every recommendation into an error.

package/src/linter/docs/README.md

@@ -0,0 +1,38 @@
+# Astrale Linter
+
+Astrale Linter is the SDK-owned authoring system that turns stable Astrale domain conventions into
+type constraints and static diagnostics.
+
+Domain authors use the ordinary project commands:
+
+```sh
+pnpm lint
+pnpm lint:fix
+pnpm typecheck
+pnpm test
+```
+
+Generated domains contain the compatible dependencies and Oxlint bridge. Authors should not need to
+assemble parser services, plugins, or analyzer configuration themselves.
+
+## Reference
+
+- [PRINCIPLES.md](./PRINCIPLES.md) defines the enforcement philosophy and rule-admission bar.
+- [JUDGMENT.md](./JUDGMENT.md) defines what must remain human or agent judgment.
+- [RULE-AUTHORING.md](./RULE-AUTHORING.md) defines identifiers, metadata, lifecycle, and testing.
+- [RULES.md](./RULES.md) is the canonical policy registry and implementation-status record.
+- [DIAGNOSTICS.md](./DIAGNOSTICS.md) defines output, tool failures, and suppressions.
+
+## Scope
+
+The implementation is authoring-only and is exposed through `@astrale-os/sdk/linter`. It is not
+re-exported from the isomorphic SDK root and must never enter a worker or browser bundle.
+
+Each executable policy has one owner:
+
+- `sdk` prevents invalid states through public types and authoring contracts.
+- `oxlint` detects reliable file-local syntax and control-flow violations.
+- `analyzer` detects project shape, import-graph, and cross-file violations.
+
+Generic JavaScript and TypeScript rules remain owned by `@astrale-os/ox`. Astrale rules retain stable
+`astrale/<slug>` identifiers regardless of their execution engine.

package/src/linter/docs/RULE-AUTHORING.md

@@ -0,0 +1,144 @@
+# Rule Authoring
+
+## Identity
+
+Every Astrale-specific domain rule has one canonical semantic identifier:
+
+```text
+astrale/<slug>
+```
+
+Examples:
+
+```text
+astrale/core-is-pure
+astrale/effects-run-in-step
+astrale/no-read-inside-mutate
+```
+
+The `astrale` namespace is declared once by the linter. The registry stores only the slug. Slugs use
+lower-case kebab case, state the invariant clearly, and avoid engine words such as `oxlint`, `ast`, or
+`typescript`.
+
+Prefer established lint vocabulary:
+
+- `no-*` prohibits a concrete pattern.
+- `require-*` requires explicit syntax or evidence.
+- `prefer-*` is advisory when valid exceptions exist.
+- A direct invariant such as `core-is-pure` is acceptable when it reads more clearly.
+
+Artificial abbreviations, trigrams, category prefixes, and monotonic numbers are not identifiers.
+Family and owner can change without renaming a rule.
+
+## Stability
+
+Identifier stability begins at `accepted`, not `proposed`:
+
+- A `proposed` rule may be renamed, merged, or removed freely.
+- An `accepted` or later rule keeps its canonical identifier.
+- If an accepted rule must be renamed, its old identifier remains a deprecated alias through at least
+  the next major SDK release.
+- A retired identifier is never assigned to a different invariant.
+
+This preserves early design freedom without maintaining an opaque surrogate code alongside every
+readable rule name.
+
+## Classification
+
+Every registry entry declares:
+
+| Field | Values |
+| --- | --- |
+| `family` | `structure`, `purity`, `schema`, `authorization`, `durability`, `graph`, `errors`, or `client` |
+| `owner` | `sdk`, `oxlint`, or `analyzer` |
+| `scope` | `node`, `file`, or `project` |
+| `automation` | `implement`, `research`, or `guidance` |
+| `default` | `error`, `warning`, or `off` |
+| `fix` | `safe`, `suggestion`, or `none` |
+| `status` | `proposed`, `accepted`, `implemented`, `enforced`, `deprecated`, or `retired` |
+
+Classification is metadata, not identity. Moving `astrale/authorize-is-explicit` from an analyzer hint
+to an SDK type invariant preserves its identifier, suppressions, documentation URL, and history.
+
+`automation` is an explicit decision, not a maturity score:
+
+- `implement` means the current contract is suitable for automation and may enter the rule lifecycle.
+- `research` means the idea is not approved for implementation. Its row must state what evidence or
+  narrower contract is missing.
+- `guidance` means the current formulation should remain knowledge or review guidance. Its row remains
+  in the registry as a decision record, with `default: off` and no fix.
+
+Changing `research` or `guidance` to `implement` requires a review of the detection contract and
+false-positive fixtures. It is never implied merely because an engine could approximate the rule.
+
+## Minimal policy specification
+
+Every entry in [RULES.md](./RULES.md) records:
+
+- A unique semantic slug.
+- Family, primary owner, scope, automation disposition, intended default severity, fix class, and
+  status.
+- One-sentence invariant.
+- For `research`, the evidence or narrower contract needed before implementation.
+- For `guidance`, why static enforcement would be misleading.
+
+Before an `implement` entry can become `accepted`, it additionally requires:
+
+- A deterministic detection contract and relevant source locations.
+- At least one valid and invalid fixture.
+- Representative legitimate alternatives and documented exceptions that must not trigger.
+
+An accepted rule should graduate to a dedicated document only when examples, options, or edge cases no
+longer fit clearly in the registry. Its filename is `<slug>.md`, for example
+`effects-run-in-step.md`.
+
+## Lifecycle
+
+```text
+proposed -> accepted -> implemented -> enforced
+                          |              |
+                          +-> deprecated +-> deprecated -> retired
+```
+
+- `proposed`: candidate policy; no compatibility guarantee and no default diagnostic.
+- `accepted`: identity, detection contract, and ownership approved.
+- `implemented`: rule exists behind an explicit experimental preset.
+- `enforced`: enabled at its documented severity in the strict preset.
+- `deprecated`: still recognized, with replacement guidance where applicable.
+- `retired`: no diagnostic is emitted; its historical identifier remains reserved.
+
+No rule moves directly from prose to `enforced`.
+
+Only entries classified `implement` may move from `proposed` to `accepted`. A `research` entry may have
+an isolated prototype for measurement, but that prototype must not emit default project diagnostics.
+A `guidance` entry does not enter the executable lifecycle unless it is narrowed and reclassified.
+
+## Severity policy
+
+- `error` means the code is structurally unsafe, invalid, or violates a settled Astrale contract.
+- `warning` means the observation is reliable but the observed pattern is risky rather than invalid in
+  every occurrence.
+- `off` means the rule is experimental, expensive, or awaiting platform support.
+
+Severity is not a proxy for implementation progress. An unimplemented rule remains `proposed` even if
+its intended default is `error`.
+
+Warnings are not a shelter for noisy heuristics. A likely false positive still consumes attention,
+creates suppressions, and weakens trust in every other diagnostic.
+
+## Owner migration
+
+Enforcement moves to the earliest reliable owner. A source rule should migrate from Oxlint or the
+analyzer to `sdk` once an SDK type, schema compilation path, or runtime authoring contract can make the
+invalid shape impossible. During migration, one owner emits the diagnostic; dual reporting is a bug.
+
+## Rule test contract
+
+Every implemented rule includes:
+
+- Minimal valid fixtures.
+- Minimal invalid fixtures with exact identifier, location, and message.
+- False-positive fixtures for documented exceptions.
+- Suppression fixtures.
+- Fix snapshots when `fix` is `safe` or `suggestion`.
+- A performance fixture when the rule walks imports, types, or compiled schema.

package/src/linter/docs/RULES.md

@@ -0,0 +1,153 @@
+# Rule Registry
+
+This is the canonical registry of Astrale-specific domain-policy candidates. It intentionally keeps
+both executable candidates and ideas that should remain guidance, so rejected automation ideas are not
+rediscovered later. The executable-status table records what is currently enforced; every other entry
+remains `proposed` regardless of its automation disposition.
+
+The canonical identifier is `astrale/<slug>`. Each section heading supplies the `family`; owner, scope,
+automation disposition, intended default, and fix class are explicit in every row. `owner` identifies
+the prospective evidence owner; it does not imply an implementation commitment.
+
+Automation dispositions are:
+
+- `implement`: deterministic, valuable, and expected to have a low false-positive rate under the
+  current contract.
+- `research`: potentially valuable, but blocked on a reliable detection contract or measured
+  false-positive evidence. It remains off and is not on the implementation roadmap.
+- `guidance`: valuable architectural advice that should not be a static diagnostic in its current
+  formulation. It remains here as a decision record.
+
+Generic JavaScript, TypeScript, React, Vitest, accessibility, and import rules remain owned by Oxlint
+and `@astrale-os/ox`; they are not duplicated here. Behavioral and live properties belong in tests or
+release checks rather than this static-rule registry.
+
+## Executable status
+
+| Rule | Owner | Status |
+| --- | --- | --- |
+| `astrale/thin-schema-composition-root` | `analyzer` | enforced |
+| `astrale/one-remote-definition-per-file` | `analyzer` | enforced |
+| `astrale/core-is-pure` | `analyzer` | enforced |
+| `astrale/core-has-no-async` | `oxlint` | enforced |
+| `astrale/no-nested-steps` | `oxlint` | enforced |
+| `astrale/no-read-inside-mutate` | `oxlint` | enforced |
+
+An `implement` disposition records that a policy passed the automation-admission judgment; it is not a
+claim that its SDK or analyzer implementation exists.
+
+## Structure
+
+| Slug | Owner | Scope | Automation | Default | Fix | Invariant and detection contract |
+| --- | --- | --- | --- | --- | --- | --- |
+| `thin-schema-composition-root` | `analyzer` | `project` | `implement` | error | none | `schema/index.ts` may import, re-export, assemble `defineSchema`, and compile `D`; schema member constructors such as `nodeClass`, `edgeClass`, `nodeInterface`, `edgeInterface`, `fn`, and `func` belong in owned modules. |
+| `thin-domain-composition-root` | `analyzer` | `project` | `research` | off | none | The domain root may assemble schema, methods, functions, deps, views, manifest, and install metadata but must not implement their behavior. |
+| `bounded-context-layer-alignment` | `analyzer` | `project` | `guidance` | off | none | Semantic contexts discovered under schema have their owned runtime/core artifacts under the same context name; composition files are excluded. |
+| `one-remote-definition-per-file` | `analyzer` | `file` | `implement` | error | none | A source file may contain at most one Astrale callable definition through `remoteMethod` or `defineRemoteFunction`; ordinary functions, callbacks, validators, and local helpers do not count. |
+| `explicit-callable-filename` | `analyzer` | `file` | `research` | off | none | A callable file uses a verb-object name such as `assign-issue.ts`, not a bare verb such as `assign.ts`; detection compares registered vocabulary with the filename. |
+| `no-technical-context-bucket` | `analyzer` | `project` | `guidance` | off | none | Domain layers should avoid dumping-ground paths such as `schema/functions`, `edges.ts`, `contracts.ts`, `runtime/handlers.ts`, or generic `helpers`/`utils` containers. |
+| `context-owned-errors` | `analyzer` | `project` | `guidance` | off | none | Context-specific errors should live in `core/<context>/errors.ts`; only cross-context errors should live in `core/errors.ts`. Runtime may throw but should not define them. |
+| `context-owned-paths` | `analyzer` | `project` | `guidance` | off | none | Exported graph path constants and constructors should live in `core/<context>/paths.ts` under the bounded context that owns the resource, not in runtime handlers. |
+| `simulation-data-isolated` | `analyzer` | `project` | `research` | off | none | Fake data, samples, capture kernels, and demo scenarios live under top-level `simulation/`, and production layers must not import them. |
+| `tests-follow-layer-ownership` | `analyzer` | `project` | `guidance` | off | none | Focused tests should live in the owning layer's `__tests__`; cross-context business workflows should live under `simulation/`. |
+| `explicit-default-props-name` | `analyzer` | `file` | `guidance` | off | none | Default-property builders should live in `properties.defaults.ts` and use an explicit `default<Entity>Props` name such as `defaultCommentProps`. |
+| `semantic-constant-filename` | `analyzer` | `file` | `guidance` | off | none | Exported vocabulary constants should live in a semantic file such as `tags/colors.constants.ts`, not a context-wide `constants.ts` dumping ground. |
+
+## Purity
+
+| Slug | Owner | Scope | Automation | Default | Fix | Invariant and detection contract |
+| --- | --- | --- | --- | --- | --- | --- |
+| `core-is-pure` | `analyzer` | `project` | `implement` | error | none | Production files under `core/` must not reach known effectful Astrale/Node packages or the project's `runtime`, `functions`, `integrations`, `client`, or `simulation` layers; detection follows resolved relative imports and excludes tests. Unknown third-party packages are not guessed to be effectful. |
+| `core-has-no-async` | `oxlint` | `file` | `implement` | error | none | Production files under `core/` must not declare async functions or async generators, or use top-level `await`/`for await`; tests are excluded. |
+| `integrations-enter-through-deps` | `analyzer` | `project` | `research` | off | none | Runtime handlers receive external clients through the domain dependency container and must not construct provider clients or import configured singletons directly. |
+| `deps-construction-has-no-effects` | `oxlint` | `file` | `research` | off | none | The dependency factory may construct clients from configuration but must not await, fetch, call the kernel, read time/randomness, or perform request-specific I/O. |
+
+## Schema
+
+| Slug | Owner | Scope | Automation | Default | Fix | Invariant and detection contract |
+| --- | --- | --- | --- | --- | --- | --- |
+| `path-schema-for-addresses` | `analyzer` | `node` | `research` | off | none | Schema parameters representing graph addresses use `pathSchema()` or `absolutePathSchema()`, not `z.string()`; name-only guesses cannot emit this diagnostic. |
+| `pathlike-at-input-boundaries` | `sdk` | `node` | `implement` | error | none | Public helpers that accept graph addresses use `Path` or `PathLike`; SDK-owned graph APIs must not publish `ref: string`-style contracts. |
+| `schema-derived-handler-types` | `oxlint` | `file` | `research` | off | none | Callable implementations use `remoteMethod`/`defineRemoteFunction` schema-derived types and must not redeclare parallel params, result, self, or context interfaces. |
+| `exact-runtime-callable-map` | `sdk` | `project` | `implement` | error | none | Methods and standalone-function maps contain every and only the callables declared by the compiled schema. |
+| `every-member-wired` | `sdk` | `project` | `implement` | error | none | Every declared method, standalone function, view, post-install function, and referenced dependency is present in the compiled install/runtime definition. |
+| `client-imports-schema-package` | `analyzer` | `project` | `research` | off | none | A separate frontend imports the published schema package and client surfaces; it must not reach through worker source for schema, core, runtime, deps, functions, or integrations. |
+
+## Authorization
+
+| Slug | Owner | Scope | Automation | Default | Fix | Invariant and detection contract |
+| --- | --- | --- | --- | --- | --- | --- |
+| `authorize-is-explicit` | `sdk` | `node` | `implement` | error | suggestion | Every method and standalone function declares `authorize`; an intentionally open callable uses an explicit empty hook. |
+| `caller-gate-names-principal` | `analyzer` | `file` | `research` | off | none | A caller-sensitive authorization check explicitly passes `auth.principal` as `who`; success through the composed handler kernel is not caller proof. |
+
+## Durability
+
+| Slug | Owner | Scope | Automation | Default | Fix | Invariant and detection contract |
+| --- | --- | --- | --- | --- | --- | --- |
+| `effects-run-in-step` | `analyzer` | `project` | `research` | off | none | Every call path from a callable to a known kernel operation, dependency I/O, clock read, randomness source, or registered effect crosses exactly one `step.run` boundary. |
+| `stable-step-identifier` | `analyzer` | `project` | `research` | off | none | Every executed `step.run` identifier resolves to stable kebab-case vocabulary; helper-owned steps may receive an identifier from callers only when every reachable call site supplies stable evidence. |
+| `no-nested-steps` | `oxlint` | `node` | `implement` | error | none | A `step.run` callback must not directly invoke another `step.run`; interprocedural double wrapping is covered by `astrale/effects-run-in-step`. |
+| `serializable-step-result` | `sdk` | `node` | `implement` | error | none | Values crossing a step boundary conform to the SDK's durable JSON-value contract; clients, functions, symbols, bigint, paths, bound nodes, and cyclic instances are rejected. |
+
+## Graph
+
+| Slug | Owner | Scope | Automation | Default | Fix | Invariant and detection contract |
+| --- | --- | --- | --- | --- | --- | --- |
+| `prefer-schema-bound-client` | `oxlint` | `file` | `research` | off | none | When a handler kernel is schema-bound, ordinary class reads, methods, links, and properties use the typed surface; raw calls require an unsupported or dynamic capability. |
+| `raw-path-only-at-boundary` | `analyzer` | `node` | `research` | off | none | `.raw` is used only for serialization, wire protocols, persistence keys, or APIs requiring strings, not for ordinary equality or typed graph calls. |
+| `no-redundant-raw-of` | `analyzer` | `node` | `implement` | error | suggestion | `rawOf()` receives a genuine `PathLike` boundary; values already typed as `Path` use `.raw`, and equality uses `.equals()`. |
+| `no-read-inside-mutate` | `oxlint` | `node` | `implement` | error | none | A `kernel.mutate` builder callback must not be async or directly invoke a known graph-read method on the same kernel receiver; only patch construction belongs inside it. Arbitrary external I/O is not guessed by this file-local rule. |
+| `do-not-reread-hydrated-node` | `analyzer` | `file` | `research` | off | none | Nodes returned by `children`, `neighbors`, `query`, or a bound read must not be immediately fetched again without an explicit fresh-snapshot reason. |
+| `pagination-intent-is-explicit` | `analyzer` | `file` | `research` | off | none | Code consuming a paged result explicitly chooses first-page access, draining, continuation, cursor persistence, or async iteration. |
+| `no-raw-database-query` | `oxlint` | `file` | `implement` | error | none | Domain code must not issue Cypher or adapter-specific database queries; it uses the typed graph API or supported query AST. |
+
+## Errors
+
+| Slug | Owner | Scope | Automation | Default | Fix | Invariant and detection contract |
+| --- | --- | --- | --- | --- | --- | --- |
+| `known-failures-use-domain-errors` | `analyzer` | `file` | `guidance` | off | none | Known not-found, invalid-transition, conflict, occupied-path, and relation failures should throw context-owned domain errors rather than generic `Error`. |
+| `domain-error-has-stable-code` | `sdk` | `node` | `implement` | error | none | Every exported domain error exposes a non-empty stable machine-readable code through the SDK error contract; the linter does not infer which context fields the business requires. |
+| `unknown-errors-propagate` | `analyzer` | `node` | `research` | off | none | A catch block must not translate every unknown kernel/provider failure into one generic domain error; only recognized failures may be mapped. |
+
+## Client
+
+| Slug | Owner | Scope | Automation | Default | Fix | Invariant and detection contract |
+| --- | --- | --- | --- | --- | --- | --- |
+| `use-canonical-shell-bridge` | `analyzer` | `project` | `research` | off | none | A domain client uses `@astrale-os/shell-react` and must not contain a local copy of session, intent-router, graph-memory, or Shell handshake infrastructure. |
+
+## Automation rationale
+
+### Research before implementation
+
+| Slug | What must be proven first |
+| --- | --- |
+| `thin-domain-composition-root` | Syntax alone does not reliably distinguish composition from small domain behavior; the accepted contract needs explicit allowed and forbidden declarations. |
+| `explicit-callable-filename` | Callable identity must come from a resolved registration symbol rather than filename or verb guessing. |
+| `simulation-data-isolated` | A narrow production-imports-simulation rule is detectable, but identifying fake data by names or contents is not; the policy should be split before acceptance. |
+| `integrations-enter-through-deps` | Detection needs SDK-owned dependency and integration identities; arbitrary client imports and factories have legitimate uses. |
+| `deps-construction-has-no-effects` | The linter must identify the dependency factory and known effect calls precisely instead of banning common syntax in similarly named files. |
+| `path-schema-for-addresses` | Graph-address intent must be visible in compiled schema metadata; parameter names such as `ref` or `path` are insufficient evidence. |
+| `schema-derived-handler-types` | The analyzer must distinguish duplicate callable contracts from legitimate local helper types. |
+| `client-imports-schema-package` | Package and deployment boundaries must be discovered reliably before source imports can be judged as worker reach-through; relative imports from a client into backend `core/` are part of the forbidden boundary. |
+| `caller-gate-names-principal` | The rule needs exact authorization-call identity and proof that the operation is caller-sensitive. |
+| `effects-run-in-step` | Reliable enforcement requires interprocedural effect summaries, known effect identities, and explicit step ownership across helpers. |
+| `stable-step-identifier` | File-local literal enforcement rejects valid helper-owned steps such as `readIssue(..., 'read-created-issue')`; project analysis or an SDK-branded identifier is required to prove every call site. |
+| `prefer-schema-bound-client` | A warning is valid only when the analyzer can prove the typed client offers the equivalent capability. |
+| `raw-path-only-at-boundary` | Type and callee-signature evidence must distinguish serialization boundaries from ordinary typed graph work. |
+| `do-not-reread-hydrated-node` | Dataflow must prove that the same hydrated value is reread and provide a machine-visible way to request a fresh snapshot. |
+| `pagination-intent-is-explicit` | The SDK must expose paged-result intent in types or methods that the analyzer can follow without guessing control flow. |
+| `unknown-errors-propagate` | The analyzer must recognize typed error guards and mappings before it can distinguish selective translation from catch-all masking. |
+| `use-canonical-shell-bridge` | Import requirements are detectable, but semantic copies of Shell infrastructure are not; the rule needs a narrower import-boundary contract. |
+
+### Keep as guidance in the current formulation
+
+| Slug | Why static enforcement would be misleading |
+| --- | --- |
+| `bounded-context-layer-alignment` | Context ownership is business semantics, and valid layers may intentionally use different projections or context boundaries. |
+| `no-technical-context-bucket` | Names such as `helpers`, `contracts`, or `edges` can indicate poor design but are not violations without understanding their contents and consumers. |
+| `context-owned-errors` | A machine cannot reliably decide whether an error is context-specific or genuinely shared. |
+| `context-owned-paths` | Resource ownership and the correct bounded context are architectural decisions; filenames cannot prove them. A narrower ban on runtime-local path declarations may be proposed separately. |
+| `tests-follow-layer-ownership` | The distinction between a focused layer test and a business scenario depends on test intent, not directory names alone. |
+| `explicit-default-props-name` | The exact builder name and filename are conventions whose value rarely justifies false positives across valid construction patterns. |
+| `semantic-constant-filename` | Whether a constants file is a dumping ground depends on cohesion and consumers, not the word `constants`. |
+| `known-failures-use-domain-errors` | Identifying a known business failure requires domain semantics; a generic `Error` ban would also reject legitimate infrastructure and assertion failures. |