@massa-ai/core 1.2.1

package/dist/services/search/smart-chunker.js

@@ -0,0 +1,67 @@
+/**
+ * Smart Chunker — dispatcher (Wave 6 N31, T16)
+ *
+ * Language/format-aware semantic chunking. All chunking logic extracted to
+ * chunker/ modules. This file dispatches by extension and re-exports.
+ */
+import path from "path";
+export { DEFAULT_CONFIG } from "./chunker/chunker-types.js";
+export { chunkMarkdown, chunkMarkdownByHeadings } from "./chunker/chunker-markdown.js";
+export { chunkJSON, chunkYAML } from "./chunker/chunker-json-yaml.js";
+export { chunkCode, findCodeBoundaries, netBraceDelta, extractFileImports, isCodeFile, CODE_EXTENSIONS } from "./chunker/chunker-code.js";
+export { postProcess, splitOversizedChunk, splitLineByChars, chunkFixed } from "./chunker/chunker-post.js";
+import { DEFAULT_CONFIG } from "./chunker/chunker-types.js";
+import { chunkMarkdown } from "./chunker/chunker-markdown.js";
+import { chunkJSON, chunkYAML } from "./chunker/chunker-json-yaml.js";
+import { chunkCode, isCodeFile, extractFileImports } from "./chunker/chunker-code.js";
+import { postProcess } from "./chunker/chunker-post.js";
+import { chunkFixed } from "./chunker/chunker-post.js";
+// ── Dispatcher ──────────────────────────────────────────────────────────────
+export function smartChunk(content, filePath, config = {}) {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    const ext = path.extname(filePath).toLowerCase();
+    const relativePath = filePath;
+    const fileImports = isCodeFile(ext) ? extractFileImports(content, ext) : undefined;
+    let chunks;
+    switch (ext) {
+        case ".md":
+        case ".mdx":
+            chunks = chunkMarkdown(content, cfg);
+            break;
+        case ".json":
+            chunks = chunkJSON(content, cfg);
+            break;
+        case ".yaml":
+        case ".yml":
+            chunks = chunkYAML(content, cfg);
+            break;
+        case ".py":
+            chunks = chunkFallback(content, cfg);
+            break;
+        default:
+            chunks = isCodeFile(ext) ? chunkCode(content, cfg) : chunkFallback(content, cfg);
+    }
+    const HEADER_BUDGET = 250;
+    const postCfg = cfg.maxChunkChars > HEADER_BUDGET
+        ? { ...cfg, maxChunkChars: cfg.maxChunkChars - HEADER_BUDGET } : cfg;
+    chunks = postProcess(chunks, postCfg);
+    const REPEAT_MIN_LINES = 5;
+    if (cfg.addFileContext) {
+        chunks = chunks.map((chunk) => {
+            const lineCount = chunk.content.split("\n").length;
+            const repeat = chunk.label && lineCount >= REPEAT_MIN_LINES;
+            const labelHeader = chunk.label
+                ? repeat ? `// Section: ${chunk.label}\n// ${chunk.label}\n// ${chunk.label}\n` : `// Section: ${chunk.label}\n`
+                : "";
+            return { ...chunk, content: `// File: ${relativePath}\n${labelHeader}${chunk.content}` };
+        });
+    }
+    if (fileImports) {
+        chunks = chunks.map((c) => ({ ...c, fileImports, parentSymbol: c.label ?? undefined }));
+    }
+    return chunks.filter((c) => c.content.trim().length > 0);
+}
+function chunkFallback(content, cfg) {
+    return chunkFixed(content, cfg);
+}
+//# sourceMappingURL=smart-chunker.js.map

package/dist/services/search/smart-chunker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-chunker.js","sourceRoot":"","sources":["../../../src/services/search/smart-chunker.ts"],"names":[],"mappings":"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"}

package/dist/services/structural/diagnostics.d.ts

@@ -0,0 +1,6 @@
+import type { ParseDiagnostic, StructuralFailureKind } from "./types.js";
+export declare const MAX_STRUCTURAL_DIAGNOSTIC_DETAILS = 10;
+export declare function diagnostic(code: string, severity: ParseDiagnostic["severity"], error: unknown): ParseDiagnostic;
+export declare function boundDiagnostics(diagnostics: readonly ParseDiagnostic[]): readonly ParseDiagnostic[];
+export declare function classifyNativeFailure(error: unknown): StructuralFailureKind;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/services/structural/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/services/structural/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAGpD,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,EACrC,KAAK,EAAE,OAAO,GACb,eAAe,CAOjB;AAED,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,SAAS,eAAe,EAAE,GACtC,SAAS,eAAe,EAAE,CAE5B;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAO3E"}

package/dist/services/structural/diagnostics.js

@@ -0,0 +1,22 @@
+export const MAX_STRUCTURAL_DIAGNOSTIC_DETAILS = 10;
+const MAX_DIAGNOSTIC_MESSAGE_LENGTH = 500;
+export function diagnostic(code, severity, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return Object.freeze({
+        code,
+        severity,
+        message: message.slice(0, MAX_DIAGNOSTIC_MESSAGE_LENGTH),
+    });
+}
+export function boundDiagnostics(diagnostics) {
+    return Object.freeze(diagnostics.slice(0, MAX_STRUCTURAL_DIAGNOSTIC_DETAILS));
+}
+export function classifyNativeFailure(error) {
+    const text = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    return text.includes("abi") ||
+        text.includes("module version") ||
+        text.includes("dlopen")
+        ? "abi"
+        : "grammar";
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/services/structural/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../../src/services/structural/diagnostics.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,CAAC;AACpD,MAAM,6BAA6B,GAAG,GAAG,CAAC;AAE1C,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,QAAqC,EACrC,KAAc;IAEd,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI;QACJ,QAAQ;QACR,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,6BAA6B,CAAC;KACzD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,WAAuC;IAEvC,OAAO,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,iCAAiC,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,MAAM,IAAI,GAAG,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACpF,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAC/B,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACvB,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}

package/dist/services/structural/fqn-codec.d.ts

@@ -0,0 +1,105 @@
+import { type StructuralSymbolKind } from "./types.js";
+import type { StructuralFqnCandidate } from "@massa-ai/shared";
+export type StructuralIdentityScope = "top_level" | "nested";
+export type StructuralIdentityOverload = "unique" | "overloaded";
+export type SignatureDigest = (canonicalSignature: string) => string;
+export interface StructuralSignatureInput {
+    language: string;
+    dialect: string;
+    qualifiedName: string;
+    kind: StructuralSymbolKind;
+    arity?: number;
+    typeTokens?: readonly string[];
+    modifiers?: readonly string[];
+}
+export interface StructuralIdentityInput extends StructuralSignatureInput {
+    file: string;
+    name: string;
+    scope: StructuralIdentityScope;
+    overload: StructuralIdentityOverload;
+}
+export interface StructuralIdentity {
+    fqn: string;
+    legacyFqn: string;
+    aliases: readonly [string];
+    file: string;
+    name: string;
+    displayName: string;
+    qualifiedName: string;
+    kind: StructuralSymbolKind;
+    canonicalSignature: string;
+    signatureHash: string;
+}
+export type { StructuralFqnCandidate } from "@massa-ai/shared";
+export type StructuralFqnResolution = {
+    found: true;
+    ambiguous: false;
+    identity: StructuralIdentity;
+} | {
+    found: false;
+    ambiguous: false;
+    fqn: string;
+} | {
+    found: false;
+    ambiguous: false;
+    legacyFqn: string;
+    candidates: readonly [];
+} | {
+    found: false;
+    ambiguous: true;
+    legacyFqn: string;
+    candidates: readonly StructuralFqnCandidate[];
+};
+export type ParsedStructuralFqn = {
+    format: "simple";
+    file: string;
+    name: string;
+} | {
+    format: "qualified";
+    file: string;
+    qualifiedName: string;
+    kind: StructuralSymbolKind;
+    signatureHash: string;
+};
+export declare function normalizeStructuralFile(file: string): string;
+export declare function canonicalizeStructuralSignature(input: StructuralSignatureInput): string;
+/**
+ * Extract the embedded schema version from a canonical signature produced by
+ * `canonicalizeStructuralSignature`. Returns `""` for any payload that does not
+ * carry a parseable version field (legacy pre-version rows, malformed input, or
+ * the synthetic `"persisted:<id>"` placeholder used by the ETL resolve stage).
+ *
+ * Read-side corruption-surface guard: callers that re-hash or compare persisted
+ * canonical signatures must route the extracted version through
+ * `assertCanonicalSignatureSupported` so a row written by NEWER code fails loud
+ * instead of silently identity-drifting.
+ */
+export declare function decodeCanonicalSignatureVersion(canonicalSignature: string): string;
+/**
+ * Decode-and-assert for persisted canonical signatures. Throws
+ * `SchemaAheadError` ONLY when the embedded version is strictly newer than the
+ * running code's `STRUCTURAL_FQN_SCHEMA_VERSION`. Legacy / malformed / missing
+ * versions pass through unchanged (forward-compat with old rows).
+ */
+export declare function assertCanonicalSignatureSupported(canonicalSignature: string): void;
+export declare const sha256SignatureDigest: SignatureDigest;
+export declare function createStructuralIdentity(input: StructuralIdentityInput, digest?: SignatureDigest): StructuralIdentity;
+export declare function formatStructuralFqn(identity: StructuralIdentity): string;
+export declare function parseStructuralFqn(fqn: string): ParsedStructuralFqn;
+export declare function structuralFqnDisplayName(fqn: string): string;
+export declare class FqnHashCollisionError extends Error {
+    readonly code: "fqn_hash_collision";
+    readonly signatureHash: string;
+    constructor(signatureHash: string);
+}
+/** Generation-scoped identity registry with collision and ambiguity enforcement. */
+export declare class StructuralFqnRegistry {
+    #private;
+    constructor(digest?: SignatureDigest);
+    register(input: StructuralIdentityInput): StructuralIdentity;
+    resolveModern(fqn: string): StructuralFqnResolution;
+    resolveLegacy(legacyFqn: string): StructuralFqnResolution;
+    /** Exact modern identity wins; otherwise treat input as a legacy alias. */
+    resolve(fqn: string): StructuralFqnResolution;
+}
+//# sourceMappingURL=fqn-codec.d.ts.map

package/dist/services/structural/fqn-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fqn-codec.d.ts","sourceRoot":"","sources":["../../../src/services/structural/fqn-codec.ts"],"names":[],"mappings":"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"}

package/dist/services/structural/fqn-codec.js

@@ -0,0 +1,272 @@
+import { createHash } from "node:crypto";
+import { STRUCTURAL_FQN_SCHEMA_VERSION, STRUCTURAL_SYMBOL_KINDS, } from "./types.js";
+import { assertSchemaSupported } from "./schema-version.js";
+const KIND_PATTERN = STRUCTURAL_SYMBOL_KINDS.join("|");
+const MODERN_SUFFIX = new RegExp(`^(.*)~(${KIND_PATTERN})~([0-9a-f]{64})$`, "u");
+const KNOWN_KIND_SUFFIX = new RegExp(`~(?:${KIND_PATTERN})~[^~]*$`, "u");
+const MODERN_LIKE_SUFFIX = /~[^~]+~[0-9a-f]+$/iu;
+const STRUCTURAL_KIND_SET = new Set(STRUCTURAL_SYMBOL_KINDS);
+function normalizedNfcText(value, label) {
+    const normalized = value.normalize("NFC").trim();
+    if (!normalized)
+        throw new TypeError(`${label} must not be empty`);
+    return normalized;
+}
+function normalizedSignatureText(value, label, lowercase = false) {
+    const normalized = normalizedNfcText(value, label).replace(/\s+/gu, " ");
+    return lowercase ? normalized.toLocaleLowerCase("en-US") : normalized;
+}
+export function normalizeStructuralFile(file) {
+    let normalized = normalizedNfcText(file, "file").replace(/\\/gu, "/");
+    if (/^[a-z]:/iu.test(normalized) || normalized.startsWith("/")) {
+        throw new TypeError("file must be a relative POSIX path");
+    }
+    if (normalized.includes("\0") || normalized.includes("#")) {
+        throw new TypeError("file contains a reserved character");
+    }
+    normalized = normalized.replace(/\/{2,}/gu, "/");
+    if (normalized.startsWith("./"))
+        normalized = normalized.slice(2);
+    const segments = normalized.split("/");
+    if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
+        throw new TypeError("file must not contain empty or dot path segments");
+    }
+    return normalized;
+}
+function normalizeSymbolText(value, label) {
+    const normalized = normalizedNfcText(value, label);
+    if (normalized.includes("#"))
+        throw new TypeError(`${label} contains reserved #`);
+    return normalized;
+}
+function hasReservedModernSuffix(value) {
+    return KNOWN_KIND_SUFFIX.test(value) || MODERN_LIKE_SUFFIX.test(value);
+}
+export function canonicalizeStructuralSignature(input) {
+    if (!STRUCTURAL_KIND_SET.has(input.kind))
+        throw new TypeError("kind is outside structural taxonomy");
+    if (input.arity !== undefined && (!Number.isInteger(input.arity) || input.arity < 0)) {
+        throw new TypeError("arity must be a non-negative integer");
+    }
+    const typeTokens = (input.typeTokens ?? []).map((token) => normalizedSignatureText(token, "type token"));
+    const modifiers = [...new Set((input.modifiers ?? []).map((modifier) => normalizedSignatureText(modifier, "modifier", true)))].sort();
+    return JSON.stringify({
+        version: STRUCTURAL_FQN_SCHEMA_VERSION,
+        language: normalizedSignatureText(input.language, "language", true),
+        dialect: normalizedSignatureText(input.dialect, "dialect", true),
+        qualifiedName: normalizeSymbolText(input.qualifiedName, "qualifiedName"),
+        kind: input.kind,
+        arity: input.arity ?? null,
+        typeTokens,
+        modifiers,
+    });
+}
+/**
+ * Extract the embedded schema version from a canonical signature produced by
+ * `canonicalizeStructuralSignature`. Returns `""` for any payload that does not
+ * carry a parseable version field (legacy pre-version rows, malformed input, or
+ * the synthetic `"persisted:<id>"` placeholder used by the ETL resolve stage).
+ *
+ * Read-side corruption-surface guard: callers that re-hash or compare persisted
+ * canonical signatures must route the extracted version through
+ * `assertCanonicalSignatureSupported` so a row written by NEWER code fails loud
+ * instead of silently identity-drifting.
+ */
+export function decodeCanonicalSignatureVersion(canonicalSignature) {
+    if (!canonicalSignature || typeof canonicalSignature !== "string")
+        return "";
+    // The synthetic ETL placeholder ("persisted:<id>") and any non-JSON legacy
+    // payload have no embedded version — treat them as unknown / legacy.
+    if (!canonicalSignature.startsWith("{"))
+        return "";
+    try {
+        const parsed = JSON.parse(canonicalSignature);
+        return typeof parsed.version === "string" ? parsed.version : "";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Decode-and-assert for persisted canonical signatures. Throws
+ * `SchemaAheadError` ONLY when the embedded version is strictly newer than the
+ * running code's `STRUCTURAL_FQN_SCHEMA_VERSION`. Legacy / malformed / missing
+ * versions pass through unchanged (forward-compat with old rows).
+ */
+export function assertCanonicalSignatureSupported(canonicalSignature) {
+    const embedded = decodeCanonicalSignatureVersion(canonicalSignature);
+    // Empty embedded version = legacy / unknown — never throw.
+    if (!embedded)
+        return;
+    assertSchemaSupported("fqn", embedded, STRUCTURAL_FQN_SCHEMA_VERSION);
+}
+export const sha256SignatureDigest = (canonicalSignature) => createHash("sha256").update(canonicalSignature, "utf8").digest("hex");
+function validateDigest(digest) {
+    if (!/^[0-9a-f]{64}$/u.test(digest)) {
+        throw new TypeError("signature digest must be a full lowercase SHA-256 hex value");
+    }
+    return digest;
+}
+export function createStructuralIdentity(input, digest = sha256SignatureDigest) {
+    const file = normalizeStructuralFile(input.file);
+    const name = normalizeSymbolText(input.name, "name");
+    const qualifiedName = normalizeSymbolText(input.qualifiedName, "qualifiedName");
+    if (input.scope !== "top_level" && input.scope !== "nested") {
+        throw new TypeError("scope must be top_level or nested");
+    }
+    if (input.overload !== "unique" && input.overload !== "overloaded") {
+        throw new TypeError("overload must be unique or overloaded");
+    }
+    if (input.scope === "top_level" && qualifiedName !== name) {
+        throw new TypeError("top-level identity requires qualifiedName to equal name");
+    }
+    const canonicalSignature = canonicalizeStructuralSignature({ ...input, qualifiedName });
+    const signatureHash = validateDigest(digest(canonicalSignature));
+    const legacyFqn = `${file}#${name}`;
+    const fqn = input.scope === "top_level" &&
+        input.overload === "unique" &&
+        !hasReservedModernSuffix(name)
+        ? legacyFqn
+        : `${file}#${qualifiedName}~${input.kind}~${signatureHash}`;
+    return Object.freeze({
+        fqn,
+        legacyFqn,
+        aliases: Object.freeze([legacyFqn]),
+        file,
+        name,
+        displayName: qualifiedName,
+        qualifiedName,
+        kind: input.kind,
+        canonicalSignature,
+        signatureHash,
+    });
+}
+export function formatStructuralFqn(identity) {
+    return identity.fqn;
+}
+export function parseStructuralFqn(fqn) {
+    const separator = fqn.indexOf("#");
+    if (separator <= 0 || separator !== fqn.lastIndexOf("#")) {
+        throw new TypeError("FQN must contain exactly one non-leading # separator");
+    }
+    const file = normalizeStructuralFile(fqn.slice(0, separator));
+    const symbolPart = fqn.slice(separator + 1);
+    if (!symbolPart)
+        throw new TypeError("FQN symbol must not be empty");
+    const modern = MODERN_SUFFIX.exec(symbolPart);
+    if (!modern) {
+        if (hasReservedModernSuffix(symbolPart)) {
+            throw new TypeError("modern FQN suffix requires a known kind and full lowercase SHA-256");
+        }
+        return { format: "simple", file, name: normalizeSymbolText(symbolPart, "name") };
+    }
+    return {
+        format: "qualified",
+        file,
+        qualifiedName: normalizeSymbolText(modern[1], "qualifiedName"),
+        kind: modern[2],
+        signatureHash: modern[3],
+    };
+}
+export function structuralFqnDisplayName(fqn) {
+    const parsed = parseStructuralFqn(fqn);
+    return parsed.format === "qualified" ? parsed.qualifiedName : parsed.name;
+}
+export class FqnHashCollisionError extends Error {
+    code = "fqn_hash_collision";
+    signatureHash;
+    constructor(signatureHash) {
+        super(`Distinct canonical signatures produced SHA-256 ${signatureHash}`);
+        this.name = "FqnHashCollisionError";
+        this.signatureHash = signatureHash;
+    }
+}
+function candidate(identity) {
+    return Object.freeze({
+        fqn: identity.fqn,
+        file: identity.file,
+        name: identity.name,
+        displayName: identity.displayName,
+        qualifiedName: identity.qualifiedName,
+        kind: identity.kind,
+        signatureHash: identity.signatureHash,
+    });
+}
+function compareCandidates(left, right) {
+    const fields = [
+        [left.file, right.file],
+        [left.qualifiedName, right.qualifiedName],
+        [left.kind, right.kind],
+        [left.signatureHash, right.signatureHash],
+    ];
+    for (const [leftValue, rightValue] of fields) {
+        if (leftValue < rightValue)
+            return -1;
+        if (leftValue > rightValue)
+            return 1;
+    }
+    return 0;
+}
+/** Generation-scoped identity registry with collision and ambiguity enforcement. */
+export class StructuralFqnRegistry {
+    #digest;
+    #canonicalByHash = new Map();
+    #identityByFqn = new Map();
+    #identitiesByLegacy = new Map();
+    constructor(digest = sha256SignatureDigest) {
+        this.#digest = digest;
+    }
+    register(input) {
+        const identity = createStructuralIdentity(input, this.#digest);
+        const priorCanonical = this.#canonicalByHash.get(identity.signatureHash);
+        if (priorCanonical !== undefined && priorCanonical !== identity.canonicalSignature) {
+            throw new FqnHashCollisionError(identity.signatureHash);
+        }
+        this.#canonicalByHash.set(identity.signatureHash, identity.canonicalSignature);
+        const priorIdentity = this.#identityByFqn.get(identity.fqn);
+        if (priorIdentity && priorIdentity.canonicalSignature !== identity.canonicalSignature) {
+            throw new Error(`fqn_identity_collision: ${identity.fqn}`);
+        }
+        if (priorIdentity)
+            return priorIdentity;
+        this.#identityByFqn.set(identity.fqn, identity);
+        const aliases = this.#identitiesByLegacy.get(identity.legacyFqn) ?? [];
+        aliases.push(identity);
+        this.#identitiesByLegacy.set(identity.legacyFqn, aliases);
+        return identity;
+    }
+    resolveModern(fqn) {
+        const identity = this.#identityByFqn.get(fqn);
+        return identity
+            ? { found: true, ambiguous: false, identity }
+            : { found: false, ambiguous: false, fqn };
+    }
+    resolveLegacy(legacyFqn) {
+        const identities = this.#identitiesByLegacy.get(legacyFqn) ?? [];
+        if (identities.length === 1) {
+            return { found: true, ambiguous: false, identity: identities[0] };
+        }
+        if (identities.length === 0) {
+            return {
+                found: false,
+                ambiguous: false,
+                legacyFqn,
+                candidates: Object.freeze([]),
+            };
+        }
+        return {
+            found: false,
+            ambiguous: true,
+            legacyFqn,
+            candidates: Object.freeze(identities.map(candidate).sort(compareCandidates)),
+        };
+    }
+    /** Exact modern identity wins; otherwise treat input as a legacy alias. */
+    resolve(fqn) {
+        const modern = this.#identityByFqn.get(fqn);
+        return modern
+            ? { found: true, ambiguous: false, identity: modern }
+            : this.resolveLegacy(fqn);
+    }
+}
+//# sourceMappingURL=fqn-codec.js.map

package/dist/services/structural/fqn-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fqn-codec.js","sourceRoot":"","sources":["../../../src/services/structural/fqn-codec.ts"],"names":[],"mappings":"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"}

package/dist/services/structural/grammar-integrity.d.ts

@@ -0,0 +1,37 @@
+import { createRequire } from "node:module";
+/**
+ * Carries the pinned and recomputed integrity values so callers can report a
+ * precise mismatch surface.
+ */
+export declare class GrammarIntegrityError extends Error {
+    readonly pkg: string;
+    readonly expected: string;
+    readonly actual: string;
+    readonly code = "GRAMMAR_INTEGRITY_MISMATCH";
+    constructor(pkg: string, expected: string, actual: string);
+}
+type RuntimeRequire = ReturnType<typeof createRequire>;
+/**
+ * Compute the canonical `sha512-<base64>` source-integrity digest for one
+ * installed package. Throws if the package root or required source files are
+ * absent.
+ */
+export declare function computePackageSourceIntegrity(requireFromCore: RuntimeRequire, packageName: string): string;
+/**
+ * Verify every pinned native grammar package against its `sourceIntegrity`
+ * pin. Runs at most once per process: subsequent calls are a no-op so the
+ * check never taxes per-request parse paths.
+ *
+ * Default behavior is ON (verifies). Set the environment variable
+ * `MASSA_AI_SKIP_GRAMMAR_INTEGRITY=1` to skip, which is intended only for
+ * local development iterations where grammar packages are intentionally
+ * patched or swapped. Production and CI default to verifying.
+ *
+ * @throws {GrammarIntegrityError} when any pinned package's recomputed
+ *   source integrity does not match its pin.
+ */
+export declare function verifyNativeGrammarIntegrity(requireFromCore?: RuntimeRequire): void;
+/** Test-only seam: reset the module-level memoization flag. */
+export declare function resetGrammarIntegrityForTests(): void;
+export {};
+//# sourceMappingURL=grammar-integrity.d.ts.map

package/dist/services/structural/grammar-integrity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar-integrity.d.ts","sourceRoot":"","sources":["../../../src/services/structural/grammar-integrity.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA2C5C;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAI5C,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM;IALzB,QAAQ,CAAC,IAAI,gCAAgC;gBAGlC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAO1B;AAED,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AA6FvD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,cAAc,EAC/B,WAAW,EAAE,MAAM,GAClB,MAAM,CA0BR;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,eAAe,GAAE,cAA+C,GAC/D,IAAI,CAiBN;AAED,+DAA+D;AAC/D,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD"}