@presolve/typescript-authority 0.2.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Presolve contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/presolve-typescript-authority.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { analyzeV2Authoring } from "../src/index.js";
+
+try {
+  let input = "";
+  for await (const chunk of process.stdin) input += chunk;
+  const request = JSON.parse(input);
+  const response = await analyzeV2Authoring(request);
+  process.stdout.write(`${JSON.stringify(response)}\n`);
+} catch (error) {
+  process.stderr.write(`presolve-typescript-authority: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@presolve/typescript-authority",
+  "version": "0.2.0-beta.1",
+  "description": "The sole TypeScript semantic-authority boundary for Presolve.",
+  "license": "MIT OR Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fierstdev/presolve.git",
+    "directory": "packages/typescript-authority"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "presolve-typescript-authority": "./bin/presolve-typescript-authority.mjs"
+  },
+  "dependencies": {
+    "@typescript/native": "npm:typescript@^7.0.2"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/src/index.js

@@ -0,0 +1,330 @@
+import { API, SymbolFlags } from "@typescript/native/unstable/async";
+import { getTokenAtPosition, SyntaxKind } from "@typescript/native/unstable/ast";
+import { dirname, relative, resolve, sep } from "node:path";
+
+export {
+  CANONICAL_INTRINSIC_KINDS,
+  classifyResolvedComponentHeritage,
+  classifyResolvedIntrinsic,
+  createCanonicalIntrinsicRegistry,
+} from "./intrinsics.js";
+export { analyzeV2Authoring, V2_AUTHORED_AUTHORITY_SCHEMA_VERSION } from "./v2-authoring.js";
+
+export const TYPESCRIPT_SEMANTIC_AUTHORITY_SCHEMA_VERSION = 1;
+export const PRIMARY_TYPESCRIPT_VERSION = "7.0.2";
+
+/**
+ * Queries TypeScript's semantic engine and returns only Presolve-owned,
+ * serializable products. Compiler domain modules must consume this boundary
+ * rather than importing concrete TypeScript APIs.
+ */
+export async function analyzeTypeScriptProject(request) {
+  validateRequest(request);
+  const configFile = resolve(request.cwd ?? process.cwd(), request.configFile);
+  const api = new API({ cwd: request.cwd ?? process.cwd() });
+
+  try {
+    const config = await api.parseConfigFile(configFile);
+    const snapshot = await api.updateSnapshot({ openProjects: [configFile] });
+    const project = snapshot.getProject(configFile);
+    if (!project) throw new Error(`TypeScript did not open project ${configFile}`);
+
+    const queries = request.queries ?? {};
+    const diagnostics = await collectDiagnostics(project.program, config);
+    const response = {
+      schemaVersion: TYPESCRIPT_SEMANTIC_AUTHORITY_SCHEMA_VERSION,
+      typeScriptVersion: PRIMARY_TYPESCRIPT_VERSION,
+      project: {
+        configFile: project.configFileName,
+        rootFiles: [...project.rootFiles].sort(),
+      },
+      diagnostics,
+      symbols: await querySymbols(project, queries.symbols ?? []),
+      componentHeritage: await queryComponentHeritage(project, queries.componentHeritage ?? []),
+      types: await queryTypes(project, queries.types ?? []),
+      contextualTypes: await queryContextualTypes(project, queries.contextualTypes ?? []),
+      signatures: await querySignatures(project, queries.signatures ?? []),
+      assignability: await queryAssignability(project, queries.assignability ?? []),
+      modules: await queryModules(project, queries.modules ?? []),
+    };
+    await snapshot.dispose();
+    return response;
+  } finally {
+    await api.close();
+  }
+}
+
+async function collectDiagnostics(program, config) {
+  const sources = [
+    ["config", config.diagnostics ?? []],
+    ["program", await program.getProgramDiagnostics()],
+    ["syntactic", await program.getSyntacticDiagnostics()],
+    ["bind", await program.getBindDiagnostics()],
+    ["semantic", await program.getSemanticDiagnostics()],
+  ];
+  return sources
+    .flatMap(([source, diagnostics]) => diagnostics.map(diagnostic => serializeDiagnostic(source, diagnostic)))
+    .sort(compareDiagnostics);
+}
+
+async function querySymbols(project, queries) {
+  return Promise.all(queries.map(async query => {
+    const symbol = await symbolAt(project, query);
+    return { id: query.id, symbol: await serializeSymbol(project, symbol) };
+  }));
+}
+
+/**
+ * Serializes the resolved direct-and-indirect base chain for a class symbol.
+ * It assigns no framework meaning: callers must classify these symbols through
+ * the canonical intrinsic registry.
+ */
+async function queryComponentHeritage(project, queries) {
+  return Promise.all(queries.map(async query => {
+    const symbol = await symbolAt(project, query);
+    return {
+      id: query.id,
+      symbol: await serializeSymbol(project, symbol),
+      bases: await resolvedBaseSymbols(project, symbol),
+    };
+  }));
+}
+
+async function queryTypes(project, queries) {
+  return Promise.all(queries.map(async query => {
+    const type = await typeAt(project, query);
+    return { id: query.id, type: await serializeType(project.checker, type) };
+  }));
+}
+
+async function queryContextualTypes(project, queries) {
+  return Promise.all(queries.map(async query => {
+    const { file, token } = await tokenAt(project, query);
+    const type = await nearestContextualType(project.checker, token, file);
+    return { id: query.id, type: await serializeType(project.checker, type) };
+  }));
+}
+
+async function querySignatures(project, queries) {
+  return Promise.all(queries.map(async query => {
+    const { file, token } = await tokenAt(project, query);
+    const signature = await nearestSignature(project.checker, token);
+    return { id: query.id, signature: await serializeSignature(project.checker, signature) };
+  }));
+}
+
+async function queryAssignability(project, queries) {
+  return Promise.all(queries.map(async query => {
+    const source = await typeAt(project, query.source);
+    const target = await typeAt(project, query.target);
+    return {
+      id: query.id,
+      assignable: Boolean(source && target && await project.checker.isTypeAssignableTo(source, target)),
+      source: await serializeType(project.checker, source),
+      target: await serializeType(project.checker, target),
+    };
+  }));
+}
+
+async function queryModules(project, queries) {
+  return Promise.all(queries.map(async query => {
+    const { file, token } = await tokenAt(project, query);
+    const symbol = await project.checker.getSymbolAtPosition(file.fileName, query.position);
+    const module = await serializeSymbol(project, symbol);
+    return {
+      id: query.id,
+      module: module && {
+        ...module,
+        specifier: token.getText(file).replace(/^(?:"|')|(?:"|')$/g, ""),
+        resolvedModulePaths: module.identity.declarationModules,
+      },
+    };
+  }));
+}
+
+async function symbolAt(project, query) {
+  const { file } = await tokenAt(project, query);
+  return project.checker.getSymbolAtPosition(file.fileName, query.position);
+}
+
+async function resolvedBaseSymbols(project, symbol) {
+  const bases = [];
+  const seen = new Set();
+  let current = await resolvedSymbol(project.checker, symbol);
+  while (current && !seen.has(current.id)) {
+    seen.add(current.id);
+    const base = await directBaseSymbol(project, current);
+    if (!base) {
+      // The compiler's structural selection points at a heritage expression,
+      // so a direct `extends Component` query resolves to Component itself.
+      // Preserve that terminal resolved base without treating source spelling
+      // as framework meaning.
+      if (bases.length === 0) bases.push(await serializeSymbol(project, current));
+      break;
+    }
+    bases.push(await serializeSymbol(project, base));
+    current = await resolvedSymbol(project.checker, base);
+  }
+  return bases;
+}
+
+async function resolvedSymbol(checker, symbol) {
+  if (!symbol) return undefined;
+  return (symbol.flags & SymbolFlags.Alias) === 0
+    ? symbol
+    : checker.getAliasedSymbol(symbol);
+}
+
+async function directBaseSymbol(project, symbol) {
+  for (const declarationHandle of symbol.declarations ?? []) {
+    const declaration = await declarationHandle.resolve();
+    for (const clause of declaration.heritageClauses ?? []) {
+      if (clause.token !== SyntaxKind.ExtendsKeyword) continue;
+      const base = clause.types?.[0]?.expression;
+      if (!base) continue;
+      const source = declaration.getSourceFile();
+      return project.checker.getSymbolAtPosition(source.fileName, base.getStart(source));
+    }
+  }
+  return undefined;
+}
+
+async function typeAt(project, query) {
+  const { file } = await tokenAt(project, query);
+  return project.checker.getTypeAtPosition(file.fileName, query.position);
+}
+
+async function tokenAt(project, query) {
+  validatePositionQuery(query);
+  const fileName = resolve(query.file);
+  const file = await project.program.getSourceFile(fileName);
+  if (!file) throw new Error(`TypeScript project does not contain ${fileName}`);
+  if (query.position < 0 || query.position > file.text.length) {
+    throw new RangeError(`position ${query.position} is outside ${fileName}`);
+  }
+  return { file, token: getTokenAtPosition(file, query.position) };
+}
+
+async function nearestContextualType(checker, token, file) {
+  for (let node = token; node; node = node.parent) {
+    const type = await checker.getContextualType(node);
+    if (type) return type;
+    if (node === file) break;
+  }
+  return undefined;
+}
+
+async function nearestSignature(checker, token) {
+  for (let node = token; node; node = node.parent) {
+    try {
+      const signature = await checker.getResolvedSignature(node);
+      if (signature) return signature;
+    } catch {
+      // TypeScript only resolves signatures for invocation-like nodes.
+    }
+  }
+  return undefined;
+}
+
+async function serializeSymbol(project, symbol) {
+  if (!symbol) return undefined;
+  const { checker } = project;
+  const declarationPaths = symbol.declarations
+    .map(declaration => String(declaration.path))
+    .sort();
+  const serialized = {
+    name: symbol.name,
+    flags: symbol.flags,
+    declarationPaths,
+    identity: identityForSymbol(project, symbol, declarationPaths),
+  };
+  if ((symbol.flags & SymbolFlags.Alias) === 0) return serialized;
+
+  const target = await checker.getAliasedSymbol(symbol);
+  return {
+    ...serialized,
+    aliasTarget: {
+      name: target.name,
+      flags: target.flags,
+      declarationPaths: target.declarations.map(declaration => String(declaration.path)).sort(),
+      identity: identityForSymbol(
+        project,
+        target,
+        target.declarations.map(declaration => String(declaration.path)).sort(),
+      ),
+      unknown: await checker.isUnknownSymbol(target),
+    },
+  };
+}
+
+function identityForSymbol(project, symbol, declarationPaths) {
+  const projectRoot = dirname(String(project.id));
+  return {
+    name: symbol.name,
+    flags: symbol.flags,
+    declarationModules: [...new Set(declarationPaths.map(path => normalizeProjectPath(projectRoot, path)))],
+  };
+}
+
+function normalizeProjectPath(projectRoot, path) {
+  const relativePath = relative(projectRoot, path);
+  return relativePath.split(sep).join("/") || ".";
+}
+
+async function serializeType(checker, type) {
+  if (!type) return undefined;
+  return {
+    text: await checker.typeToString(type),
+    flags: type.flags,
+    error: type.isErrorType(),
+  };
+}
+
+async function serializeSignature(checker, signature) {
+  if (!signature) return undefined;
+  const parameters = await signature.getParameters();
+  return {
+    parameterTypes: await Promise.all(parameters.map(async parameter => ({
+      name: parameter.name,
+      type: await serializeType(checker, await checker.getTypeOfSymbol(parameter)),
+    }))),
+    returnType: await serializeType(checker, await checker.getReturnTypeOfSignature(signature)),
+  };
+}
+
+function serializeDiagnostic(source, diagnostic) {
+  return {
+    source,
+    code: diagnostic.code,
+    category: diagnostic.category,
+    file: diagnostic.fileName,
+    start: diagnostic.pos,
+    end: diagnostic.end,
+    message: diagnostic.text,
+  };
+}
+
+function compareDiagnostics(left, right) {
+  return (left.file ?? "").localeCompare(right.file ?? "")
+    || left.start - right.start
+    || left.code - right.code
+    || left.source.localeCompare(right.source);
+}
+
+function validateRequest(request) {
+  if (!request || typeof request !== "object" || typeof request.configFile !== "string") {
+    throw new TypeError("TypeScript authority requests require a configFile");
+  }
+  if (request.cwd !== undefined && typeof request.cwd !== "string") {
+    throw new TypeError("TypeScript authority cwd must be a string");
+  }
+  if (request.queries !== undefined && (typeof request.queries !== "object" || Array.isArray(request.queries))) {
+    throw new TypeError("TypeScript authority queries must be an object");
+  }
+}
+
+function validatePositionQuery(query) {
+  if (!query || typeof query.file !== "string" || !Number.isInteger(query.position)) {
+    throw new TypeError("TypeScript authority position queries require file and integer position");
+  }
+}

package/src/intrinsics.js

@@ -0,0 +1,49 @@
+export const CANONICAL_INTRINSIC_KINDS = Object.freeze([
+  "component", "state", "action", "computed", "effect", "slot", "context",
+  "provide", "consume", "form", "serialize", "field", "validate", "submit",
+  "resource", "loader", "server_action", "opaque", "environment_public",
+]);
+
+/** Builds a registry exclusively from TypeScript-resolved canonical targets. */
+export function createCanonicalIntrinsicRegistry(entries) {
+  const registry = new Map();
+  for (const entry of entries) {
+    if (!CANONICAL_INTRINSIC_KINDS.includes(entry.kind)) {
+      throw new TypeError(`unknown Presolve intrinsic kind ${entry.kind}`);
+    }
+    const identity = targetIdentity(entry.symbol);
+    if (!identity) throw new TypeError(`intrinsic ${entry.kind} has no resolved target identity`);
+    const key = identityKey(identity);
+    if (registry.has(key)) throw new TypeError(`duplicate canonical intrinsic identity for ${entry.kind}`);
+    registry.set(key, { kind: entry.kind, identity });
+  }
+  return registry;
+}
+
+/** Classifies a use-site result from `analyzeTypeScriptProject`, never its spelling. */
+export function classifyResolvedIntrinsic(registry, symbol) {
+  const identity = targetIdentity(symbol);
+  return identity ? registry.get(identityKey(identity)) : undefined;
+}
+
+/**
+ * Classifies a resolved base-class chain without relying on the local spelling
+ * of a component base. The TypeScript adapter supplies the chain, including
+ * aliases and indirect bases; the registry supplies framework meaning.
+ */
+export function classifyResolvedComponentHeritage(registry, bases) {
+  for (const base of bases) {
+    const intrinsic = classifyResolvedIntrinsic(registry, base);
+    if (intrinsic?.kind === "component") return intrinsic;
+  }
+  return undefined;
+}
+
+function targetIdentity(symbol) {
+  return symbol?.aliasTarget?.identity ?? symbol?.identity;
+}
+
+function identityKey(identity) {
+  if (!identity || !Array.isArray(identity.declarationModules)) return "";
+  return JSON.stringify([identity.name, identity.flags, [...identity.declarationModules].sort()]);
+}

package/src/v2-authoring.js

@@ -0,0 +1,145 @@
+import {
+  analyzeTypeScriptProject,
+  classifyResolvedComponentHeritage,
+  classifyResolvedIntrinsic,
+  createCanonicalIntrinsicRegistry,
+} from "./index.js";
+
+export const V2_AUTHORED_AUTHORITY_SCHEMA_VERSION = 4;
+
+/**
+ * Resolves explicit source positions for the implemented decorator-free V2
+ * authoring forms. Syntax selection belongs to the caller; this bridge owns
+ * only TypeScript resolution and canonical-registry classification.
+ */
+export async function analyzeV2Authoring(request) {
+  validateV2AuthoringRequest(request);
+  const queries = {
+    symbols: [
+      ...(request.canonical.component ? [{ id: "canonical:component", ...request.canonical.component }] : []),
+      ...(request.canonical.state ? [{ id: "canonical:state", ...request.canonical.state }] : []),
+      ...(request.canonical.action ? [{ id: "canonical:action", ...request.canonical.action }] : []),
+      ...(request.canonical.effect ? [{ id: "canonical:effect", ...request.canonical.effect }] : []),
+      ...(request.canonical.environment ? [{ id: "canonical:environment", ...request.canonical.environment }] : []),
+      ...request.states.map(site => ({ id: `state:${site.id}`, file: site.file, position: site.position })),
+      ...request.actions.map(site => ({ id: `action:${site.id}`, file: site.file, position: site.position })),
+      ...request.effects.map(site => ({ id: `effect:${site.id}`, file: site.file, position: site.position })),
+      ...request.environmentPublic.flatMap(site => [
+        { id: `environment-object:${site.id}`, file: site.file, position: site.objectPosition },
+        { id: `environment-property:${site.id}`, file: site.file, position: site.propertyPosition },
+      ]),
+    ],
+    componentHeritage: request.components.map(site => ({
+      id: `component:${site.id}`,
+      file: site.file,
+      position: site.position,
+    })),
+  };
+  const authority = await analyzeTypeScriptProject({
+    configFile: request.configFile,
+    ...(request.cwd === undefined ? {} : { cwd: request.cwd }),
+    queries,
+  });
+  const symbols = new Map(authority.symbols.map(entry => [entry.id, entry.symbol]));
+  const registry = createCanonicalIntrinsicRegistry([
+    ...(request.canonical.component ? [{ kind: "component", symbol: symbols.get("canonical:component") }] : []),
+    ...(request.canonical.state ? [{ kind: "state", symbol: symbols.get("canonical:state") }] : []),
+    ...(request.canonical.action ? [{ kind: "action", symbol: symbols.get("canonical:action") }] : []),
+    ...(request.canonical.effect ? [{ kind: "effect", symbol: symbols.get("canonical:effect") }] : []),
+    ...(request.canonical.environment ? [{ kind: "environment_public", symbol: symbols.get("canonical:environment") }] : []),
+  ]);
+  return {
+    schemaVersion: V2_AUTHORED_AUTHORITY_SCHEMA_VERSION,
+    diagnostics: authority.diagnostics,
+    components: authority.componentHeritage.flatMap(site => {
+      const intrinsic = classifyResolvedComponentHeritage(registry, site.bases);
+      return intrinsic ? [{ id: stripPrefix(site.id, "component:"), identity: intrinsic.identity }] : [];
+    }),
+    states: request.states.flatMap(site => {
+      const intrinsic = classifyResolvedIntrinsic(registry, symbols.get(`state:${site.id}`));
+      return intrinsic?.kind === "state" ? [{ id: site.id, identity: intrinsic.identity }] : [];
+    }),
+    actions: request.actions.flatMap(site => {
+      const intrinsic = classifyResolvedIntrinsic(registry, symbols.get(`action:${site.id}`));
+      return intrinsic?.kind === "action" ? [{ id: site.id, identity: intrinsic.identity }] : [];
+    }),
+    effects: request.effects.flatMap(site => {
+      const intrinsic = classifyResolvedIntrinsic(registry, symbols.get(`effect:${site.id}`));
+      return intrinsic?.kind === "effect" ? [{ id: site.id, identity: intrinsic.identity }] : [];
+    }),
+    environmentPublic: request.environmentPublic.flatMap(site => {
+      const receiver = classifyResolvedIntrinsic(registry, symbols.get(`environment-object:${site.id}`));
+      const member = resolvedIdentity(symbols.get(`environment-property:${site.id}`));
+      return receiver?.kind === "environment_public" && member?.name === "public"
+        && sameDeclarationModules(member, receiver.identity)
+        ? [{ id: site.id, identity: member }]
+        : [];
+    }),
+  };
+}
+
+function validateV2AuthoringRequest(request) {
+  if (!request || typeof request !== "object" || typeof request.configFile !== "string") {
+    throw new TypeError("V2 authoring authority requests require a configFile");
+  }
+  if (!request.canonical || typeof request.canonical !== "object") {
+    throw new TypeError("V2 authoring authority requests require canonical framework positions");
+  }
+  if (request.schemaVersion !== V2_AUTHORED_AUTHORITY_SCHEMA_VERSION) {
+    throw new TypeError(`unsupported V2 authoring authority schema version ${request.schemaVersion}`);
+  }
+  for (const kind of ["component", "state", "action", "effect", "environment"]) {
+    if (request.canonical[kind] !== undefined) {
+      validatePosition(request.canonical[kind], `canonical ${kind}`);
+    }
+  }
+  for (const [kind, sites] of [["component", request.components], ["state", request.states], ["action", request.actions], ["effect", request.effects]]) {
+    if (!Array.isArray(sites)) throw new TypeError(`V2 authoring ${kind} sites must be an array`);
+    if (sites.length > 0 && request.canonical[kind] === undefined) {
+      throw new TypeError(`V2 authoring ${kind} sites require a canonical ${kind} position`);
+    }
+    const ids = new Set();
+    for (const site of sites) {
+      if (!site || typeof site.id !== "string" || !site.id || ids.has(site.id)) {
+        throw new TypeError(`V2 authoring ${kind} sites require unique non-empty ids`);
+      }
+      ids.add(site.id);
+      validatePosition(site, `${kind} site`);
+    }
+  }
+  if (!Array.isArray(request.environmentPublic)) {
+    throw new TypeError("V2 authoring environment public sites must be an array");
+  }
+  if (request.environmentPublic.length > 0 && request.canonical.environment === undefined) {
+    throw new TypeError("V2 authoring environment public sites require a canonical environment position");
+  }
+  const ids = new Set();
+  for (const site of request.environmentPublic) {
+    if (!site || typeof site.id !== "string" || !site.id || ids.has(site.id)) {
+      throw new TypeError("V2 authoring environment public sites require unique non-empty ids");
+    }
+    ids.add(site.id);
+    validatePosition({ file: site.file, position: site.objectPosition }, "environment public object site");
+    validatePosition({ file: site.file, position: site.propertyPosition }, "environment public property site");
+  }
+}
+
+function validatePosition(value, label) {
+  if (!value || typeof value.file !== "string" || !Number.isInteger(value.position)) {
+    throw new TypeError(`V2 authoring ${label} requires file and integer position`);
+  }
+}
+
+function stripPrefix(value, prefix) {
+  return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}
+
+function resolvedIdentity(symbol) {
+  return symbol?.aliasTarget?.identity ?? symbol?.identity;
+}
+
+function sameDeclarationModules(left, right) {
+  if (!left || !right) return false;
+  return JSON.stringify([...left.declarationModules].sort())
+    === JSON.stringify([...right.declarationModules].sort());
+}

package/test/semantic-authority.test.mjs

@@ -0,0 +1,265 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+import {
+  analyzeTypeScriptProject,
+  analyzeV2Authoring,
+  classifyResolvedComponentHeritage,
+  classifyResolvedIntrinsic,
+  createCanonicalIntrinsicRegistry,
+  PRIMARY_TYPESCRIPT_VERSION,
+  TYPESCRIPT_SEMANTIC_AUTHORITY_SCHEMA_VERSION,
+  V2_AUTHORED_AUTHORITY_SCHEMA_VERSION,
+} from "../src/index.js";
+
+const root = resolve(import.meta.dirname, "../../..");
+const configFile = resolve(root, "tests/typescript-compatibility/tsconfig.json");
+const file = resolve(root, "tests/typescript-compatibility/src/compatibility.tsx");
+const source = readFileSync(file, "utf8");
+
+function position(text, occurrence = 0) {
+  let start = -1;
+  for (let index = 0; index <= occurrence; index += 1) {
+    start = source.indexOf(text, start + 1);
+  }
+  assert.notEqual(start, -1, `missing ${text}`);
+  return start;
+}
+
+test("the authority adapter owns TypeScript semantic queries", async () => {
+  const result = await analyzeTypeScriptProject({
+    configFile,
+    queries: {
+      symbols: [{ id: "overload", file, position: position('overload("typed")') }],
+      types: [{ id: "generic", file, position: position("box: Box<LocalAlias>") }],
+      contextualTypes: [{ id: "callback", file, position: position("value => value.length") }],
+      signatures: [{ id: "call", file, position: position('overload("typed")') }],
+      assignability: [
+        {
+          id: "number-to-number",
+          source: { file, position: position("selected =") },
+          target: { file, position: position("selected =") },
+        },
+        {
+          id: "string-to-number",
+          source: { file, position: position("packageValue;") },
+          target: { file, position: position("selected =") },
+        },
+      ],
+      modules: [
+        { id: "package-export", file, position: position("@compat/library") },
+        { id: "re-export", file, position: position("@compat/library", 1) },
+      ],
+    },
+  });
+
+  assert.equal(result.schemaVersion, TYPESCRIPT_SEMANTIC_AUTHORITY_SCHEMA_VERSION);
+  assert.equal(result.typeScriptVersion, PRIMARY_TYPESCRIPT_VERSION);
+  assert.equal(result.diagnostics.length, 0);
+  assert.equal(result.symbols[0].symbol.name, "overload");
+  assert.equal(result.symbols[0].symbol.aliasTarget.name, "overload");
+  assert.match(result.symbols[0].symbol.aliasTarget.declarationPaths[0], /@compat\/library\/types\/index\.d\.ts$/);
+  assert.deepEqual(result.symbols[0].symbol.aliasTarget.identity.declarationModules, ["node_modules/@compat/library/types/index.d.ts"]);
+  assert.equal(result.types[0].type.text, "Box<LocalAlias>");
+  assert.equal(result.contextualTypes[0].type.text, "number");
+  assert.deepEqual(result.signatures[0].signature.parameterTypes.map(parameter => parameter.type.text), ["string"]);
+  assert.equal(result.signatures[0].signature.returnType.text, "number");
+  assert.equal(result.assignability[0].assignable, true);
+  assert.equal(result.assignability[1].assignable, false);
+  assert.match(result.modules[0].module.declarationPaths[0], /@compat\/library\/types\/index\.d\.ts$/);
+  assert.equal(result.modules[0].module.specifier, "@compat/library");
+  assert.deepEqual(result.modules[0].module.resolvedModulePaths, ["node_modules/@compat/library/types/index.d.ts"]);
+  assert.deepEqual(result.modules[1].module.resolvedModulePaths, result.modules[0].module.resolvedModulePaths);
+});
+
+test("the authority adapter preserves native TypeScript diagnostics", async () => {
+  const diagnostics = await analyzeTypeScriptProject({
+    configFile: resolve(root, "tests/typescript-compatibility/diagnostics/tsconfig.json"),
+  });
+  assert.deepEqual(diagnostics.diagnostics.map(diagnostic => diagnostic.code), [2322, 2345]);
+  assert(diagnostics.diagnostics.every(diagnostic => diagnostic.source === "semantic"));
+});
+
+test("canonical intrinsics classify resolved exports rather than local spellings", async () => {
+  const frameworkFile = resolve(root, "tests/framework-public-api/src/PublicCounter.tsx");
+  const frameworkSource = readFileSync(frameworkFile, "utf8");
+  const frameworkResult = await analyzeTypeScriptProject({
+    configFile: resolve(root, "tests/framework-public-api/tsconfig.json"),
+    queries: {
+      symbols: [
+        { id: "component-import", file: frameworkFile, position: frameworkSource.indexOf("component,") },
+        { id: "component-use", file: frameworkFile, position: frameworkSource.indexOf("@component()") + 1 },
+      ],
+    },
+  });
+  const registry = createCanonicalIntrinsicRegistry([
+    { kind: "component", symbol: frameworkResult.symbols[0].symbol },
+  ]);
+  assert.equal(classifyResolvedIntrinsic(registry, frameworkResult.symbols[1].symbol)?.kind, "component");
+  assert.equal(classifyResolvedIntrinsic(registry, { identity: { name: "component", flags: 0, declarationModules: [] } }), undefined);
+});
+
+test("component heritage preserves aliases and indirect bases for registry classification", async () => {
+  const frameworkFile = resolve(root, "tests/framework-public-api/src/V2Counter.tsx");
+  const frameworkSource = readFileSync(frameworkFile, "utf8");
+  const result = await analyzeTypeScriptProject({
+    configFile: resolve(root, "tests/framework-public-api/tsconfig.json"),
+    queries: {
+      symbols: [{ id: "component-import", file: frameworkFile, position: frameworkSource.indexOf("Component") }],
+      componentHeritage: [{ id: "counter", file: frameworkFile, position: frameworkSource.indexOf("V2Counter extends") }],
+    },
+  });
+  const registry = createCanonicalIntrinsicRegistry([
+    { kind: "component", symbol: result.symbols[0].symbol },
+  ]);
+  const heritage = result.componentHeritage[0];
+  assert.deepEqual(heritage.bases.map(base => base.name), ["V2CounterBase", "Component"]);
+  assert.equal(classifyResolvedComponentHeritage(registry, heritage.bases)?.kind, "component");
+});
+
+test("the V2 authoring bridge resolves canonical component, State, Action, Effect, and Environment evidence", async () => {
+  const frameworkFile = resolve(root, "tests/framework-public-api/src/V2Counter.tsx");
+  const frameworkSource = readFileSync(frameworkFile, "utf8");
+  const result = await analyzeV2Authoring({
+    schemaVersion: V2_AUTHORED_AUTHORITY_SCHEMA_VERSION,
+    configFile: resolve(root, "tests/framework-public-api/tsconfig.json"),
+    canonical: {
+      component: { file: frameworkFile, position: frameworkSource.indexOf("Component") },
+      state: { file: frameworkFile, position: frameworkSource.indexOf("state") },
+      action: { file: frameworkFile, position: frameworkSource.indexOf("action") },
+      effect: { file: frameworkFile, position: frameworkSource.indexOf("effect") },
+      environment: { file: frameworkFile, position: frameworkSource.indexOf("runtimeEnvironment") },
+    },
+    components: [{ id: "counter", file: frameworkFile, position: frameworkSource.indexOf("V2Counter extends") }],
+    states: [{ id: "count", file: frameworkFile, position: frameworkSource.indexOf("state(0)") }],
+    actions: [{ id: "increment", file: frameworkFile, position: frameworkSource.indexOf("action(()") }],
+    effects: [{ id: "syncTitle", file: frameworkFile, position: frameworkSource.indexOf("effect(()") }],
+    environmentPublic: [
+      {
+        id: "application-name",
+        file: frameworkFile,
+        objectPosition: frameworkSource.indexOf("runtimeEnvironment.public"),
+        propertyPosition: frameworkSource.indexOf("runtimeEnvironment.public") + "runtimeEnvironment.".length,
+      },
+      {
+        id: "lookalike",
+        file: frameworkFile,
+        objectPosition: frameworkSource.indexOf("lookalikeEnvironment.public"),
+        propertyPosition: frameworkSource.indexOf("lookalikeEnvironment.public") + "lookalikeEnvironment.".length,
+      },
+    ],
+  });
+  assert.equal(result.schemaVersion, V2_AUTHORED_AUTHORITY_SCHEMA_VERSION);
+  assert.equal(result.diagnostics.length, 0);
+  assert.deepEqual(result.components.map(entry => entry.id), ["counter"]);
+  assert.deepEqual(result.states.map(entry => entry.id), ["count"]);
+  assert.deepEqual(result.actions.map(entry => entry.id), ["increment"]);
+  assert.deepEqual(result.effects.map(entry => entry.id), ["syncTitle"]);
+  assert.deepEqual(result.environmentPublic.map(entry => entry.id), ["application-name"]);
+  assert.equal(result.components[0].identity.name, "Component");
+  assert.equal(result.states[0].identity.name, "state");
+  assert.equal(result.actions[0].identity.name, "action");
+  assert.equal(result.effects[0].identity.name, "effect");
+  assert.equal(result.environmentPublic[0].identity.name, "public");
+});
+
+test("the V2 authoring bridge supports a component-only discovery phase", async () => {
+  const frameworkFile = resolve(root, "tests/framework-public-api/src/V2Counter.tsx");
+  const frameworkSource = readFileSync(frameworkFile, "utf8");
+  const result = await analyzeV2Authoring({
+    schemaVersion: V2_AUTHORED_AUTHORITY_SCHEMA_VERSION,
+    configFile: resolve(root, "tests/framework-public-api/tsconfig.json"),
+    canonical: {
+      component: { file: frameworkFile, position: frameworkSource.indexOf("Component") },
+    },
+    components: [{ id: "counter", file: frameworkFile, position: frameworkSource.indexOf("V2Counter extends") }],
+    states: [],
+    actions: [],
+    effects: [],
+    environmentPublic: [],
+  });
+  assert.deepEqual(result.components.map(entry => entry.id), ["counter"]);
+  assert.deepEqual(result.states, []);
+  assert.deepEqual(result.actions, []);
+  assert.deepEqual(result.effects, []);
+});
+
+test("the V2 authoring bridge recognizes a direct Component heritage-expression query", async () => {
+  const frameworkFile = resolve(root, "tests/framework-public-api/src/V2Counter.tsx");
+  const frameworkSource = readFileSync(frameworkFile, "utf8");
+  const directFile = resolve(root, "tests/framework-public-api/src/DirectV2.tsx");
+  const directSource = readFileSync(directFile, "utf8");
+  const result = await analyzeV2Authoring({
+    schemaVersion: V2_AUTHORED_AUTHORITY_SCHEMA_VERSION,
+    configFile: resolve(root, "tests/framework-public-api/tsconfig.json"),
+    canonical: {
+      component: { file: frameworkFile, position: frameworkSource.indexOf("Component") },
+    },
+    components: [{ id: "direct", file: directFile, position: directSource.lastIndexOf("Component") }],
+    states: [],
+    actions: [],
+    effects: [],
+    environmentPublic: [],
+  });
+  assert.deepEqual(result.components.map(entry => entry.id), ["direct"]);
+  assert.equal(result.components[0].identity.name, "Component");
+});
+
+test("the V2 authoring bridge resolves environment evidence without a component query", async () => {
+  const frameworkFile = resolve(root, "tests/framework-public-api/src/V2Counter.tsx");
+  const frameworkSource = readFileSync(frameworkFile, "utf8");
+  const result = await analyzeV2Authoring({
+    schemaVersion: V2_AUTHORED_AUTHORITY_SCHEMA_VERSION,
+    configFile: resolve(root, "tests/framework-public-api/tsconfig.json"),
+    canonical: {
+      environment: { file: frameworkFile, position: frameworkSource.indexOf("runtimeEnvironment") },
+    },
+    components: [],
+    states: [],
+    actions: [],
+    effects: [],
+    environmentPublic: [{
+      id: "application-name",
+      file: frameworkFile,
+      objectPosition: frameworkSource.indexOf("runtimeEnvironment.public"),
+      propertyPosition: frameworkSource.indexOf("runtimeEnvironment.public") + "runtimeEnvironment.".length,
+    }],
+  });
+  assert.deepEqual(result.components, []);
+  assert.deepEqual(result.environmentPublic.map(entry => entry.id), ["application-name"]);
+});
+
+test("the V2 authoring executable speaks the versioned stdin/stdout bridge protocol", () => {
+  const frameworkFile = resolve(root, "tests/framework-public-api/src/V2Counter.tsx");
+  const frameworkSource = readFileSync(frameworkFile, "utf8");
+  const result = spawnSync(
+    process.execPath,
+    [resolve(import.meta.dirname, "../bin/presolve-typescript-authority.mjs")],
+    {
+      input: JSON.stringify({
+        schemaVersion: V2_AUTHORED_AUTHORITY_SCHEMA_VERSION,
+        configFile: resolve(root, "tests/framework-public-api/tsconfig.json"),
+        canonical: {
+          component: { file: frameworkFile, position: frameworkSource.indexOf("Component") },
+          state: { file: frameworkFile, position: frameworkSource.indexOf("state") },
+          action: { file: frameworkFile, position: frameworkSource.indexOf("action") },
+          effect: { file: frameworkFile, position: frameworkSource.indexOf("effect") },
+          environment: { file: frameworkFile, position: frameworkSource.indexOf("runtimeEnvironment") },
+        },
+        components: [{ id: "counter", file: frameworkFile, position: frameworkSource.indexOf("V2Counter extends") }],
+        states: [{ id: "count", file: frameworkFile, position: frameworkSource.indexOf("state(0)") }],
+        actions: [{ id: "increment", file: frameworkFile, position: frameworkSource.indexOf("action(()") }],
+        effects: [{ id: "syncTitle", file: frameworkFile, position: frameworkSource.indexOf("effect(()") }],
+        environmentPublic: [],
+      }),
+      encoding: "utf8",
+    },
+  );
+  assert.equal(result.status, 0, result.stderr);
+  const response = JSON.parse(result.stdout);
+  assert.equal(response.schemaVersion, V2_AUTHORED_AUTHORITY_SCHEMA_VERSION);
+  assert.deepEqual(response.components.map(entry => entry.id), ["counter"]);
+});