@astrale-os/sdk 0.4.11 → 0.4.13

package/src/domain/build-spec.ts

@@ -24,11 +24,11 @@ import type { Schema } from '@astrale-os/kernel-dsl'
 import { AbsolutePath } from '@astrale-os/kernel-core'
 import { hashInstallGraph, serialize, zodToJsonSchema } from '@astrale-os/kernel-core/domain'
 
-import type { AnyRemoteHandler } from '../method/single'
-import type { RemoteDomain } from './define'
+import type { AnyRemoteHandler } from '../method/single.js'
+import type { RemoteDomain } from './define.js'
 
-import { extractBinding } from './contract'
-import { materializeRemoteDomain } from './define'
+import { extractBinding } from './contract.js'
+import { materializeRemoteDomain } from './define.js'
 
 /**
  * Build the install-ready wire graph for a domain served at `url`: materialize

package/src/domain/contract.ts

@@ -14,7 +14,7 @@ import type {
 } from '@astrale-os/kernel-api/routed'
 import type { BoundMethod } from '@astrale-os/kernel-core/domain'
 
-import type { AnyRemoteHandler } from '../method/single'
+import type { AnyRemoteHandler } from '../method/single.js'
 
 export function toSdkContract(method: BoundMethod<AnyRemoteHandler>): MountableContract {
   const handler = method.handler as {

package/src/domain/define.ts

@@ -14,17 +14,17 @@ import type { Core, Schema } from '@astrale-os/kernel-dsl'
 
 import { bindMethods, compileDomain } from '@astrale-os/kernel-core/domain'
 
-import type { DomainManifest } from '../config/define-domain'
-import type { AnyRemoteFunctionDef, ViewDef } from '../define'
-import type { SchemaMethodsImpl } from '../method/class'
-import type { AnyRemoteHandler } from '../method/single'
+import type { DomainManifest } from '../config/define-domain.js'
+import type { AnyRemoteFunctionDef, ViewDef } from '../define/index.js'
+import type { SchemaMethodsImpl } from '../method/class.js'
+import type { AnyRemoteHandler } from '../method/single.js'
 
 import {
   assertFunctionsMatchSchema,
   buildFunctionSchemas,
   DEFAULT_FUNCTIONS_FOLDER,
-} from './extend-functions'
-import { buildViewDeclarations, buildViewSchemas, DEFAULT_VIEWS_FOLDER } from './extend-views'
+} from './extend-functions.js'
+import { buildViewDeclarations, buildViewSchemas, DEFAULT_VIEWS_FOLDER } from './extend-views.js'
 
 export type RemoteDomainConfig<S extends Schema, TDeps> = {
   schema: S

package/src/domain/extend-functions.ts

@@ -22,9 +22,9 @@ import type { Schema } from '@astrale-os/kernel-dsl'
 
 import { zodToJsonSchema } from '@astrale-os/kernel-core/domain'
 
-import type { AnyRemoteFunctionDef } from '../define/remote-function'
+import type { AnyRemoteFunctionDef } from '../define/remote-function.js'
 
-import { resolveBinding } from './binding'
+import { resolveBinding } from './binding.js'
 
 /**
  * Default URL segment for a function's worker route (`<url>/functions/<slug>`).

package/src/domain/extend-views.ts

@@ -29,9 +29,9 @@ import {
   type EdgeEndpoint,
 } from '@astrale-os/kernel-dsl'
 
-import type { ViewDef } from '../define/view'
+import type { ViewDef } from '../define/view.js'
 
-import { joinWorkerPath, resolveBinding } from './binding'
+import { joinWorkerPath, resolveBinding } from './binding.js'
 
 /**
  * Default URL segment for a view's worker route (`<url>/views/<slug>`). Names the

package/src/domain/index.ts

@@ -1,4 +1,4 @@
-export { defineRemoteDomain } from './define'
-export type { RemoteDomain, RemoteDomainConfig } from './define'
-export { buildInstallGraph, buildInstallGraphHash } from './build-spec'
-export { toSdkContract } from './contract'
+export { defineRemoteDomain } from './define.js'
+export type { RemoteDomain, RemoteDomainConfig } from './define.js'
+export { buildInstallGraph, buildInstallGraphHash } from './build-spec.js'
+export { toSdkContract } from './contract.js'

package/src/index.ts

@@ -14,15 +14,15 @@ export type {
   ClassMethodsImpl,
   InterfaceMethodsImpl,
   SchemaMethodsImpl,
-} from './method'
-export { remoteMethod, remoteClassMethods, remoteInterfaceMethods } from './method'
+} from './method/index.js'
+export { remoteMethod, remoteClassMethods, remoteInterfaceMethods } from './method/index.js'
 
 // ─── Domain configuration (astrale.config.ts) ────────────────────────────
 // The author-facing way to declare a standalone domain + how it deploys. The
 // runtime-domain COMPILER (`defineRemoteDomain`) is internal machinery — reach
 // it via the `@astrale-os/sdk/domain` subpath when hand-rolling a worker, or
 // (preferred) use `domainWorkerEntry` from `@astrale-os/sdk/server`.
-export { defineDomain, deploy, defineAdapter } from './config'
+export { defineDomain, deploy, defineAdapter } from './config/index.js'
 export type {
   DefineDomainConfig,
   DomainDefinition,
@@ -35,10 +35,10 @@ export type {
   DomainInfo,
   WatchCtx,
   WatchHandle,
-} from './config'
+} from './config/index.js'
 
 // ─── Install graph (advanced) ────────────────────────────────────────────
-export { buildInstallGraph, buildInstallGraphHash } from './domain'
+export { buildInstallGraph, buildInstallGraphHash } from './domain/index.js'
 
 // ─── Graph patching (advanced) ────────────────────────────────────────
 // Author-facing patch types, re-exported from kernel-core (the single source).
@@ -67,20 +67,20 @@ export type {
 // the reserved views / functions folder, keyed by its map slug; the same
 // entry's `render` / `execute` (+ auth hooks) is mounted as a worker route by
 // `createRemoteServer`.
-export { defineView, defineRemoteFunction } from './define'
+export { defineView, defineRemoteFunction } from './define/index.js'
 export type {
   ViewDef,
   ViewRenderContext,
   RemoteFunctionAuthorizeContext,
   RemoteFunctionDef,
   RemoteFunctionContext,
-} from './define'
+} from './define/index.js'
 
 // ─── Durable-shaped steps ────────────────────────────────────────────────
-export type { Step } from './step'
+export type { Step } from './step/index.js'
 
-// ─── Request lifecycle ───────────────────────────────────────────────────
-export type { Defer, DeferredTask } from './defer'
+// ─── Invocation capabilities ─────────────────────────────────────────────
+export type { Defer, DeferredTask, Sleep } from '@astrale-os/kernel-server'
 
 // ─── Server ──────────────────────────────────────────────────────────────
 // `createRemoteServer` dynamically imports `@hono/node-server` via `./server/start`.
@@ -94,8 +94,8 @@ export type { Defer, DeferredTask } from './defer'
 // module load time. Exporting it from the barrel poisons browser bundlers
 // (Vite/esbuild) that transitively load every re-export. Consumers that need it
 // import from './deploy' directly.
-export { MetaSchema } from './deploy/meta'
-export type { Meta } from './deploy/meta'
+export { MetaSchema } from './deploy/meta.js'
+export type { Meta } from './deploy/meta.js'
 
 // ─── Route binding (re-exported from kernel-api for consumer convenience) ─
 export type {
@@ -110,22 +110,22 @@ export type {
 } from '@astrale-os/kernel-api/routed'
 
 // ─── Auth ────────────────────────────────────────────────────────────────
-export type { RemoteIdentityConfig, AuthenticateResult } from './auth'
+export type { RemoteIdentityConfig, AuthenticateResult } from './auth/index.js'
 export type {
   DomainAuthority,
   FunctionContextApi,
   FunctionCredentialOptions,
   FunctionKernelOptions,
   MintIssuedParams,
-} from './auth'
+} from './auth/index.js'
 export {
   authenticateRequest,
   buildComposedGrant,
   makeFunctionContext,
   signCredential,
-} from './auth'
-export { AuthMissingError, AuthInvalidError } from './auth'
-export { assertPerm, requireOwnership, READ, EDIT, USE, SHARE, ALL } from './auth'
+} from './auth/index.js'
+export { AuthMissingError, AuthInvalidError } from './auth/index.js'
+export { assertPerm, requireOwnership, READ, EDIT, USE, SHARE, ALL } from './auth/index.js'
 export type {
   AuthContext,
   Attestation,
@@ -137,11 +137,11 @@ export type {
 export { selfGrant } from '@astrale-os/kernel-core'
 
 // ─── Dispatch (escape hatch for custom integrations) ─────────────────────
-export { SdkDispatcher, type SdkDispatcherConfig } from './dispatch'
+export { SdkDispatcher, type SdkDispatcherConfig } from './dispatch/index.js'
 export {
   AuthorizationDeniedError,
   MethodNotFoundError,
   SdkValidationError,
   SdkResultValidationError,
-} from './dispatch'
-export type { SelfResult, TypedSelf } from './dispatch'
+} from './dispatch/index.js'
+export type { SelfResult, TypedSelf } from './dispatch/index.js'

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.