@helyx/core 0.2.1 → 0.2.3

package/dist/help-runtime.d.ts

@@ -0,0 +1,66 @@
+import { type HelpFaq, type HelpReleaseStatus } from "./help.js";
+export type HelpRuntimeSource = {
+    kind: "website";
+    url: string;
+    contentHash: string;
+} | {
+    kind: "generic";
+    comparisons: Array<{
+        id: string;
+        area: string;
+        contentHash: string;
+        url: string;
+        question: string;
+    }>;
+} | {
+    kind: "custom";
+};
+export interface HelpRuntimeFaq {
+    id: string;
+    areaCode: string;
+    area: string;
+    areaName: string;
+    moduleId: string | null;
+    question: string;
+    answerMarkdown: string;
+    answerText: string;
+    releaseStatus: HelpReleaseStatus;
+    deploymentSupport: HelpFaq["deploymentSupport"];
+    context: string[];
+    /** Exact centrally approved content identity; no staff identity or internal file path. */
+    approvedRevision: string;
+    authoringHash: string;
+    source: HelpRuntimeSource;
+    contentHash: string;
+}
+export interface HelpRuntimeCollection {
+    schemaVersion: 1;
+    revision: string;
+    faqs: HelpRuntimeFaq[];
+}
+export interface HelpSemanticArtifact {
+    schemaVersion: 1;
+    revision: string;
+    collection: HelpRuntimeCollection;
+    manifest: {
+        sourceRevision: string;
+        createdAt: string;
+        embeddingIdentity: string;
+        dimensions: 384;
+        representation: "question-area-v1";
+        retrievalPolicy: "conservative-v1" | "conservative-v2" | "conservative-v3" | "conservative-v4" | "conservative-v5";
+    };
+    vectors: Array<{
+        id: string;
+        inputHash: string;
+        values: number[];
+    }>;
+}
+export declare function createHelpRuntimeFaq(value: Omit<HelpRuntimeFaq, "contentHash">): HelpRuntimeFaq;
+export declare function createHelpRuntimeCollection(input: readonly HelpRuntimeFaq[]): HelpRuntimeCollection;
+export declare function parseHelpRuntimeCollection(input: unknown): HelpRuntimeCollection;
+/** Adapt an already validated release bundle; no provider or authoring state is implied. */
+export declare function helpRuntimeFromLegacy(input: HelpFaq[]): HelpRuntimeCollection;
+export declare function createHelpSemanticArtifact(input: Omit<HelpSemanticArtifact, "schemaVersion" | "revision">): HelpSemanticArtifact;
+export declare function parseHelpSemanticArtifact(value: unknown): HelpSemanticArtifact;
+//# sourceMappingURL=help-runtime.d.ts.map

package/dist/help-runtime.js

@@ -0,0 +1,221 @@
+import { createHash } from "node:crypto";
+import { createHelpCollection, } from "./help.js";
+const checksum = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const validHash = (value) => typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
+const object = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid Help runtime object");
+    return value;
+};
+const text = (value, max) => {
+    if (typeof value !== "string" || !value.trim() || value.length > max)
+        throw new Error("Invalid Help runtime text");
+    return value;
+};
+const publicUrl = (value) => {
+    const url = new URL(text(value, 2000));
+    if (url.origin !== "https://docs.helyx.gg" ||
+        url.username ||
+        url.password ||
+        url.search ||
+        !/^#help-faq-[1-9]\d{5}$/u.test(url.hash))
+        throw new Error("Invalid Help runtime source URL");
+    return url.href;
+};
+function content(value) {
+    const faq = object(value), id = text(faq.id, 6), areaCode = text(faq.areaCode, 3), area = text(faq.area, 200), source = object(faq.source);
+    if (!/^[1-9]\d{5}$/u.test(id) ||
+        id.endsWith("000") ||
+        id.slice(0, 3) !== areaCode ||
+        typeof faq.approvedRevision !== "string" ||
+        !/^[1-9]\d{0,17}$/u.test(faq.approvedRevision) ||
+        !validHash(faq.authoringHash))
+        throw new Error("Invalid Help runtime identity");
+    let provenance;
+    if (source.kind === "website") {
+        const url = publicUrl(source.url);
+        if (["900", "901"].includes(areaCode) ||
+            !validHash(source.contentHash) ||
+            new URL(url).hash !== `#help-faq-${id}`)
+            throw new Error("Invalid Help website provenance");
+        provenance = { kind: "website", url, contentHash: source.contentHash };
+    }
+    else if (source.kind === "generic") {
+        if (areaCode !== "900" ||
+            area !== "platform:generic" ||
+            !Array.isArray(source.comparisons) ||
+            source.comparisons.length < 2 ||
+            source.comparisons.length > 100)
+            throw new Error("Invalid Help generic provenance");
+        const comparisons = source.comparisons
+            .map((input) => {
+            const ref = object(input), id = text(ref.id, 6), area = text(ref.area, 200), url = publicUrl(ref.url);
+            if (!/^[1-9]\d{5}$/u.test(id) ||
+                ["900", "901"].includes(id.slice(0, 3)) ||
+                id.endsWith("000") ||
+                area.startsWith("platform:") ||
+                !validHash(ref.contentHash) ||
+                new URL(url).hash !== `#help-faq-${id}`)
+                throw new Error("Invalid Help generic comparison");
+            return {
+                id,
+                area,
+                contentHash: ref.contentHash,
+                url,
+                question: text(ref.question, 600),
+            };
+        })
+            .sort((a, b) => a.id.localeCompare(b.id));
+        if (new Set(comparisons.map((ref) => ref.id)).size !== comparisons.length ||
+            new Set(comparisons.map((ref) => ref.area)).size < 2)
+            throw new Error("Invalid Help comparison identity");
+        provenance = { kind: "generic", comparisons };
+    }
+    else if (source.kind === "custom" &&
+        areaCode === "901" &&
+        area === "platform:custom")
+        provenance = { kind: "custom" };
+    else
+        throw new Error("Invalid Help provenance kind");
+    if (faq.moduleId !== null &&
+        (typeof faq.moduleId !== "string" ||
+            !/^helyx\.[a-z0-9-]+$/u.test(faq.moduleId)))
+        throw new Error("Invalid Help runtime module");
+    if (!["live", "testing", "planned", "alpha", "reference", "unknown"].includes(String(faq.releaseStatus)) ||
+        !["both", "hosted", "self-hosted", "not_declared"].includes(String(faq.deploymentSupport)) ||
+        !Array.isArray(faq.context) ||
+        faq.context.length > 30)
+        throw new Error("Invalid Help runtime availability");
+    if (source.kind !== "website" &&
+        (faq.moduleId !== null ||
+            faq.releaseStatus !== "reference" ||
+            faq.deploymentSupport !== "not_declared"))
+        throw new Error("Curated Help does not declare module availability");
+    return {
+        id,
+        areaCode,
+        area,
+        areaName: text(faq.areaName, 200),
+        moduleId: faq.moduleId,
+        question: text(faq.question, 600),
+        answerMarkdown: text(faq.answerMarkdown, 100000),
+        answerText: text(faq.answerText, 100000),
+        releaseStatus: faq.releaseStatus,
+        deploymentSupport: faq.deploymentSupport,
+        context: faq.context.map((value) => text(value, 10000)),
+        approvedRevision: faq.approvedRevision,
+        authoringHash: faq.authoringHash,
+        source: provenance,
+    };
+}
+export function createHelpRuntimeFaq(value) {
+    const canonical = content(value);
+    return { ...canonical, contentHash: checksum(canonical) };
+}
+export function createHelpRuntimeCollection(input) {
+    if (input.length > 5000)
+        throw new Error("Help runtime collection is too large");
+    const faqs = input
+        .map((faq) => {
+        const record = createHelpRuntimeFaq(faq);
+        if (record.contentHash !== faq.contentHash)
+            throw new Error("Help runtime FAQ checksum mismatch");
+        return record;
+    })
+        .sort((a, b) => a.id.localeCompare(b.id));
+    if (new Set(faqs.map((faq) => faq.id)).size !== faqs.length)
+        throw new Error("Duplicate Help runtime ID");
+    return { schemaVersion: 1, revision: checksum(faqs), faqs };
+}
+export function parseHelpRuntimeCollection(input) {
+    const value = object(input);
+    if (value.schemaVersion !== 1 || !Array.isArray(value.faqs))
+        throw new Error("Unsupported Help runtime collection");
+    const collection = createHelpRuntimeCollection(value.faqs);
+    if (collection.revision !== value.revision)
+        throw new Error("Help runtime collection checksum mismatch");
+    return collection;
+}
+/** Adapt an already validated release bundle; no provider or authoring state is implied. */
+export function helpRuntimeFromLegacy(input) {
+    return createHelpRuntimeCollection(createHelpCollection(input).faqs.map((faq) => createHelpRuntimeFaq({
+        id: faq.id,
+        areaCode: faq.moduleCode,
+        area: faq.area,
+        areaName: faq.areaName,
+        moduleId: faq.moduleId,
+        question: faq.question,
+        answerMarkdown: faq.answerMarkdown,
+        answerText: faq.answerText,
+        releaseStatus: faq.releaseStatus,
+        deploymentSupport: faq.deploymentSupport,
+        context: faq.context,
+        approvedRevision: "1",
+        authoringHash: faq.contentHash,
+        source: {
+            kind: "website",
+            url: faq.sourceUrl,
+            contentHash: faq.contentHash,
+        },
+    })));
+}
+export function createHelpSemanticArtifact(input) {
+    const collection = parseHelpRuntimeCollection(input.collection), manifest = input.manifest;
+    if (!validHash(manifest.sourceRevision) ||
+        !Number.isFinite(Date.parse(manifest.createdAt)) ||
+        !manifest.embeddingIdentity ||
+        manifest.embeddingIdentity.length > 500 ||
+        manifest.dimensions !== 384 ||
+        manifest.representation !== "question-area-v1" ||
+        ![
+            "conservative-v1",
+            "conservative-v2",
+            "conservative-v3",
+            "conservative-v4",
+            "conservative-v5",
+        ].includes(manifest.retrievalPolicy) ||
+        !Array.isArray(input.vectors) ||
+        input.vectors.length !== collection.faqs.length)
+        throw new Error("Invalid Help semantic manifest");
+    const canonicalManifest = {
+        sourceRevision: manifest.sourceRevision,
+        createdAt: manifest.createdAt,
+        embeddingIdentity: manifest.embeddingIdentity,
+        dimensions: 384,
+        representation: "question-area-v1",
+        retrievalPolicy: manifest.retrievalPolicy,
+    };
+    const vectors = [...input.vectors]
+        .sort((a, b) => a.id.localeCompare(b.id))
+        .map((vector, index) => {
+        if (vector.id !== collection.faqs[index]?.id ||
+            !validHash(vector.inputHash) ||
+            !Array.isArray(vector.values) ||
+            vector.values.length !== 384 ||
+            vector.values.some((value) => !Number.isFinite(value)) ||
+            Math.abs(Math.hypot(...vector.values) - 1) > 0.0001)
+            throw new Error("Invalid Help semantic vector alignment");
+        return {
+            id: vector.id,
+            inputHash: vector.inputHash,
+            values: [...vector.values],
+        };
+    });
+    const canonical = {
+        schemaVersion: 1,
+        collection,
+        manifest: canonicalManifest,
+        vectors,
+    };
+    return { ...canonical, revision: checksum(canonical) };
+}
+export function parseHelpSemanticArtifact(value) {
+    const artifact = object(value);
+    if (artifact.schemaVersion !== 1)
+        throw new Error("Unsupported Help semantic artifact");
+    const result = createHelpSemanticArtifact(artifact);
+    if (result.revision !== artifact.revision)
+        throw new Error("Help semantic artifact checksum mismatch");
+    return result;
+}
+//# sourceMappingURL=help-runtime.js.map

package/dist/help.d.ts

@@ -0,0 +1,123 @@
+export declare const HELP_COLLECTION_SCHEMA_VERSION = 2;
+export declare const HELP_QUESTION_MAX_LENGTH = 600;
+export declare const HELP_DOCS_URL = "https://docs.helyx.gg/";
+export interface HelpArea {
+    code: string;
+    area: string;
+    name: string;
+}
+export type HelpReleaseStatus = "live" | "testing" | "planned" | "alpha" | "reference" | "unknown";
+export interface HelpFaq {
+    /** Module/area 100–999 followed by FAQ 001–999; neither number is reused. */
+    id: string;
+    moduleCode: string;
+    area: string;
+    areaName: string;
+    moduleId: string | null;
+    question: string;
+    answerMarkdown: string;
+    answerText: string;
+    sourceUrl: string;
+    sourcePath: string;
+    releaseStatus: HelpReleaseStatus;
+    deploymentSupport: "both" | "hosted" | "self-hosted" | "not_declared";
+    context: string[];
+    contentHash: string;
+}
+export interface HelpCollection {
+    schemaVersion: 2;
+    revision: string;
+    faqs: HelpFaq[];
+}
+export type HelpSearchResult = {
+    mode: "lexical";
+    revision: string;
+} & ({
+    kind: "answer";
+    faq: HelpFaq;
+} | {
+    kind: "choices";
+    faqs: HelpFaq[];
+} | {
+    kind: "no_match";
+    reason: "empty" | "weak_match";
+    docsUrl: string;
+} | {
+    kind: "invalid";
+    reason: "too_long";
+});
+/** Explicit field order makes hashes independent of JSON property order. */
+export declare function helpFaqContent(faq: Omit<HelpFaq, "contentHash">): {
+    id: string;
+    moduleCode: string;
+    area: string;
+    areaName: string;
+    moduleId: string | null;
+    question: string;
+    answerMarkdown: string;
+    answerText: string;
+    sourceUrl: string;
+    sourcePath: string;
+    releaseStatus: HelpReleaseStatus;
+    deploymentSupport: "both" | "hosted" | "self-hosted" | "not_declared";
+    context: string[];
+};
+export declare function hashHelpFaq(faq: Omit<HelpFaq, "contentHash">): string;
+export declare function createHelpCollection(faqs: readonly HelpFaq[]): HelpCollection;
+/** Validate persisted/build input before it can enter retrieval or packaging. */
+export declare function parseHelpCollection(value: unknown): HelpCollection;
+/** Provider-free matching shared by bundled Help and the staff approved preview. */
+export interface HelpLexicalDocument {
+    id: string;
+    question: string;
+    area: string;
+    areaName: string;
+    answerText: string;
+}
+export type HelpLexicalResult<T> = {
+    mode: "lexical";
+    revision: string;
+} & ({
+    kind: "answer";
+    faq: T;
+} | {
+    kind: "choices";
+    faqs: T[];
+} | {
+    kind: "no_match";
+    reason: "empty" | "weak_match";
+    docsUrl: string;
+} | {
+    kind: "invalid";
+    reason: "too_long";
+});
+export declare const normaliseHelpQuestion: (text: string) => string;
+export declare function createHelpLexicalSearch<T extends HelpLexicalDocument>(faqs: readonly T[], revision: string, copy?: (faq: T) => T): (question: string) => HelpLexicalResult<T>;
+/** Conservative local baseline. Scores are ranking signals, not probabilities. */
+export declare function createHelpSearch(input: HelpCollection): (question: string) => HelpLexicalResult<HelpFaq>;
+export declare const HELP_PUBLISHED_SOURCE_URL = "https://docs.helyx.gg/help-sources.json";
+export interface HelpPublishedSourceRecord {
+    faq: HelpFaq;
+    sourceKind: "dedicated_faq" | "guide_question";
+    pageTitle: string;
+    sourceLine: number;
+    sourceAnswerHash: string;
+    issues: string[];
+}
+export interface HelpPublishedSourceFeed {
+    schemaVersion: 1;
+    revision: string;
+    sourceRevision: string;
+    nextModuleCode: number;
+    nextGeneralCode: number;
+    groups: Array<{
+        code: string;
+        area: string;
+        name: string;
+        nextFaq: number;
+    }>;
+    records: HelpPublishedSourceRecord[];
+}
+export declare function createHelpPublishedSources(input: Omit<HelpPublishedSourceFeed, "schemaVersion" | "revision">): HelpPublishedSourceFeed;
+export declare function parseHelpPublishedSources(value: unknown): HelpPublishedSourceFeed;
+//# sourceMappingURL=help.d.ts.map