@neuraloom/contracts 0.0.0-stage → 0.1.23

package/dist/lib/graph-id.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256Hex16 = sha256Hex16;
+exports.normalizeRepoPathposix = normalizeRepoPathposix;
+exports.stableKeyFile = stableKeyFile;
+exports.stableKeySymbol = stableKeySymbol;
+exports.stableKeyApiRoute = stableKeyApiRoute;
+exports.stableKeyDbTable = stableKeyDbTable;
+exports.stableKeySqlMigration = stableKeySqlMigration;
+exports.stableKeyRlsPolicy = stableKeyRlsPolicy;
+exports.stableKeyDbIndex = stableKeyDbIndex;
+exports.formatProofSliceRef = formatProofSliceRef;
+const SEP = "\u001f";
+function rotr32(x, n) {
+    return ((x >>> n) | (x << (32 - n))) >>> 0;
+}
+function ch32(x, y, z) {
+    return ((x & y) ^ (~x & z)) >>> 0;
+}
+function maj32(x, y, z) {
+    return ((x & y) ^ (x & z) ^ (y & z)) >>> 0;
+}
+function bigSigma0(a) {
+    return (rotr32(a, 2) ^ rotr32(a, 13) ^ rotr32(a, 22)) >>> 0;
+}
+function bigSigma1(e) {
+    return (rotr32(e, 6) ^ rotr32(e, 11) ^ rotr32(e, 25)) >>> 0;
+}
+function lilSigma0(x) {
+    return (rotr32(x, 7) ^ rotr32(x, 18) ^ (x >>> 3)) >>> 0;
+}
+function lilSigma1(x) {
+    return (rotr32(x, 17) ^ rotr32(x, 19) ^ (x >>> 10)) >>> 0;
+}
+/** SHA256 K constants (FIPS 180-4) */
+const SHA256_K = [
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+/**
+ * RFC 6234 SHA-256 over UTF-8 bytes (parity with Node `createHash('sha256').update(s,'utf8')`).
+ * Browser-safe: no Node builtins.
+ */
+function sha256Utf8DigestBytes(messageUtf8) {
+    const len = messageUtf8.length;
+    const kPad = (56 - ((len + 1) % 64) + 64) % 64;
+    const paddedLen = len + 1 + kPad + 8;
+    const padded = new Uint8Array(paddedLen);
+    padded.set(messageUtf8);
+    padded[len] = 0x80;
+    const bits = BigInt(len) * 8n;
+    const dv = new DataView(padded.buffer);
+    dv.setBigUint64(paddedLen - 8, bits, false);
+    let hh0 = 0x6a09e667;
+    let hh1 = 0xbb67ae85;
+    let hh2 = 0x3c6ef372;
+    let hh3 = 0xa54ff53a;
+    let hh4 = 0x510e527f;
+    let hh5 = 0x9b05688c;
+    let hh6 = 0x1f83d9ab;
+    let hh7 = 0x5be0cd19;
+    const w = new Uint32Array(64);
+    const blockView = new DataView(padded.buffer);
+    for (let offset = 0; offset < paddedLen; offset += 64) {
+        for (let t = 0; t < 16; t += 1) {
+            w[t] = blockView.getUint32(offset + t * 4, false);
+        }
+        for (let t = 16; t < 64; t += 1) {
+            w[t] = (lilSigma1(w[t - 2]) + w[t - 7] + lilSigma0(w[t - 15]) + w[t - 16]) >>> 0;
+        }
+        let a = hh0;
+        let b = hh1;
+        let c = hh2;
+        let d = hh3;
+        let e = hh4;
+        let f = hh5;
+        let g = hh6;
+        let h = hh7;
+        for (let t = 0; t < 64; t += 1) {
+            let t1 = (h + bigSigma1(e)) >>> 0;
+            t1 = (t1 + ch32(e, f, g)) >>> 0;
+            t1 = (t1 + SHA256_K[t]) >>> 0;
+            t1 = (t1 + w[t]) >>> 0;
+            const t2 = (bigSigma0(a) + maj32(a, b, c)) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        hh0 = (hh0 + a) >>> 0;
+        hh1 = (hh1 + b) >>> 0;
+        hh2 = (hh2 + c) >>> 0;
+        hh3 = (hh3 + d) >>> 0;
+        hh4 = (hh4 + e) >>> 0;
+        hh5 = (hh5 + f) >>> 0;
+        hh6 = (hh6 + g) >>> 0;
+        hh7 = (hh7 + h) >>> 0;
+    }
+    const out = new Uint8Array(32);
+    const outDv = new DataView(out.buffer);
+    outDv.setUint32(0, hh0, false);
+    outDv.setUint32(4, hh1, false);
+    outDv.setUint32(8, hh2, false);
+    outDv.setUint32(12, hh3, false);
+    outDv.setUint32(16, hh4, false);
+    outDv.setUint32(20, hh5, false);
+    outDv.setUint32(24, hh6, false);
+    outDv.setUint32(28, hh7, false);
+    return out;
+}
+const HEX16 = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "a", "b", "c", "d", "e", "f"];
+function digestToHex16(digest) {
+    let s = "";
+    for (let i = 0; i < 8; i += 1) {
+        const byte = digest[i];
+        s += HEX16[byte >>> 4] + HEX16[byte & 15];
+    }
+    return s;
+}
+function sha256Hex16(input) {
+    const bytes = new TextEncoder().encode(input);
+    const digest = sha256Utf8DigestBytes(bytes);
+    return digestToHex16(digest);
+}
+function normalizeRepoPathposix(path) {
+    const p = path.replace(/\\/g, "/").replace(/^\/+/, "");
+    return p.length > 0 ? p : ".";
+}
+function stableKeyFile(repoRelativePath) {
+    return `file:${normalizeRepoPathposix(repoRelativePath)}`;
+}
+function stableKeySymbol(repoRelativePath, symbolName) {
+    return `symbol:${normalizeRepoPathposix(repoRelativePath)}#${symbolName}`;
+}
+function stableKeyApiRoute(method, routePath) {
+    const m = method.trim().toUpperCase();
+    const rp = routePath.trim().startsWith("/") ? routePath.trim() : `/${routePath.trim()}`;
+    return `api_route:${m}:${rp}`;
+}
+function stableKeyDbTable(schema, table) {
+    return `db_table:${schema}.${table}`;
+}
+function stableKeySqlMigration(fileName) {
+    return `sql_migration:${normalizeRepoPathposix(fileName)}`;
+}
+function stableKeyRlsPolicy(schema, policyName) {
+    return `rls_policy:${schema}.${policyName}`;
+}
+function stableKeyDbIndex(schema, indexName) {
+    return `db_index:${schema}.${indexName}`;
+}
+/**
+ * Deterministic proof ref used as `kg_stable_key` / indexer correlation ID.
+ * Pattern matches `KgProofSliceRefSchema` in contracts.
+ */
+function formatProofSliceRef(layer, ontologyType, naturalKey) {
+    const hash = sha256Hex16([layer, ontologyType, naturalKey].join(SEP));
+    return `${layer}:${ontologyType}:${hash}`;
+}

package/dist/lib/step-navigation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Graph-aware workflow step navigation (MS06-T5 / #745).
+ * Uses canonical WORKFLOW_STEPS order + WorkflowState read-model steps — no parallel state shape.
+ */
+import type { WorkflowStepDefinition } from "../constants/workflow-registry";
+import type { WorkflowStepState } from "../schemas/workflow-progression";
+/** Optional graph context from GET .../workflow/state (same `WorkflowStepState` rows). */
+export type StepNavigationGraphContext = {
+    readonly steps: readonly WorkflowStepState[];
+    /** Server `currentStepId`; combined with derived focus when absent. */
+    readonly workflowFocusStepId?: string | null;
+};
+export type StepNavigationKind = "linear" | "graph_focus" | "unknown";
+export interface StepNavigation {
+    current: WorkflowStepDefinition | null;
+    previous: string | null;
+    next: string | null;
+    nextName: string | null;
+    /** Resolved next step id when `next` is set; null at end of workflow or unknown. */
+    nextStepId: string | null;
+    dashboard: string;
+    kind: StepNavigationKind;
+    /** Set when `kind === 'unknown'` — no graph steps; linear routing only. */
+    unknownReason?: string | null;
+}
+/**
+ * Derives the workflow “focus” step for navigation: running → blocked/failed →
+ * completed_with_errors → same first-not_started-after-completed spine as buildWorkflowState.
+ */
+export declare function deriveNavigationFocusStepId(steps: readonly WorkflowStepState[]): string | null;
+/**
+ * Step URLs for a project. When `graph` is provided, the next target prefers an
+ * upstream blocking/focus step over naive linear order (fixes stuck “Implement” / #629).
+ */
+export declare function getStepNavigation(projectId: string, currentStepId: string, graph?: StepNavigationGraphContext): StepNavigation;

package/dist/lib/step-navigation.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Graph-aware workflow step navigation (MS06-T5 / #745).
+ * Uses canonical WORKFLOW_STEPS order + WorkflowState read-model steps — no parallel state shape.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveNavigationFocusStepId = deriveNavigationFocusStepId;
+exports.getStepNavigation = getStepNavigation;
+const workflow_registry_1 = require("../constants/workflow-registry");
+const UNKNOWN_NO_STEPS = "Workflow graph state unavailable; using linear order only.";
+const SOFTWARE_STEP_IDS = new Set(workflow_registry_1.WORKFLOW_STEPS.map((s) => s.id));
+function usesChannelSpineSteps(steps) {
+    if (steps.length === 0) {
+        return false;
+    }
+    return steps.some((s) => !SOFTWARE_STEP_IDS.has(s.id));
+}
+function resolveProjectStepHref(projectId, pageRoute) {
+    return pageRoute.replace("[id]", projectId);
+}
+function orderStepsByRegistry(steps) {
+    if (!Array.isArray(steps)) {
+        return [];
+    }
+    if (usesChannelSpineSteps(steps)) {
+        return [...steps];
+    }
+    const byId = new Map(steps.map((s) => [s.stepId, s]));
+    const ordered = [];
+    for (const def of workflow_registry_1.WORKFLOW_STEPS) {
+        const row = byId.get(def.id);
+        if (row !== undefined) {
+            ordered.push(row);
+        }
+    }
+    return ordered;
+}
+/**
+ * Derives the workflow “focus” step for navigation: running → blocked/failed →
+ * completed_with_errors → same first-not_started-after-completed spine as buildWorkflowState.
+ */
+function deriveNavigationFocusStepId(steps) {
+    if (steps.length === 0) {
+        return null;
+    }
+    const ordered = orderStepsByRegistry(steps);
+    const running = ordered.find((s) => s.status === "running");
+    if (running !== undefined) {
+        return running.id;
+    }
+    const blocked = ordered.find((s) => s.status === "blocked" || s.status === "failed");
+    if (blocked !== undefined) {
+        return blocked.id;
+    }
+    const degraded = ordered.find((s) => s.status === "completed_with_errors");
+    if (degraded !== undefined) {
+        return degraded.id;
+    }
+    const ALIASED_NAV_KEYS = new Set(["schema", "knowledge", "deployments"]);
+    const aliasedGap = ordered.find((s) => !s.complete &&
+        (s.evidenceSource === "mixed_invalid" ||
+            s.evidenceSource === "incomplete" ||
+            (ALIASED_NAV_KEYS.has(s.id) &&
+                (s.status === "not_started" || s.status === "completed_with_errors"))));
+    if (aliasedGap !== undefined) {
+        return aliasedGap.id;
+    }
+    const lastCompleteIdx = ordered
+        .map((s) => s.status)
+        .lastIndexOf("completed");
+    const nextAfterCompleted = ordered[lastCompleteIdx + 1];
+    if (nextAfterCompleted?.status === "not_started") {
+        return nextAfterCompleted.id;
+    }
+    if (lastCompleteIdx === -1) {
+        return ordered[0]?.id ?? null;
+    }
+    return null;
+}
+function resolveFocusId(ctx) {
+    const derived = deriveNavigationFocusStepId(ctx.steps);
+    const sid = ctx.workflowFocusStepId;
+    if (sid !== null && sid !== undefined && sid.length > 0) {
+        if (usesChannelSpineSteps(ctx.steps)) {
+            const ordered = orderStepsByRegistry(ctx.steps);
+            const serverIdx = ordered.findIndex((s) => s.id === sid);
+            const derivedIdx = derived !== null ? ordered.findIndex((s) => s.id === derived) : -1;
+            if (serverIdx >= 0 && derivedIdx >= 0) {
+                return serverIdx <= derivedIdx ? sid : derived;
+            }
+            if (serverIdx >= 0) {
+                return sid;
+            }
+        }
+        else {
+            const serverDef = (0, workflow_registry_1.getWorkflowStep)(sid);
+            const derivedDef = derived !== null ? (0, workflow_registry_1.getWorkflowStep)(derived) : null;
+            if (serverDef !== null && derivedDef !== null) {
+                return serverDef.order <= derivedDef.order ? sid : derived;
+            }
+            if (serverDef !== null) {
+                return sid;
+            }
+        }
+    }
+    return derived;
+}
+function getChannelSpineNavigation(projectId, currentStepId, graph) {
+    const ordered = orderStepsByRegistry(graph.steps);
+    const idx = ordered.findIndex((s) => s.id === currentStepId);
+    const prevStep = idx > 0 ? ordered[idx - 1] : undefined;
+    const linearNextStep = idx >= 0 && idx < ordered.length - 1 ? ordered[idx + 1] : undefined;
+    const focusId = resolveFocusId({ ...graph, steps: ordered });
+    let nextStep = linearNextStep;
+    let kind = "linear";
+    if (focusId !== null && linearNextStep !== undefined) {
+        const focusStep = ordered.find((s) => s.id === focusId);
+        const focusIdx = ordered.findIndex((s) => s.id === focusId);
+        const nextIdx = ordered.findIndex((s) => s.id === linearNextStep.id);
+        if (focusStep !== undefined &&
+            focusIdx >= 0 &&
+            nextIdx >= 0 &&
+            focusIdx > idx && // focus must be strictly ahead of current (no backward jumps on film spine)
+            focusIdx < nextIdx &&
+            (focusStep.status === "blocked" ||
+                focusStep.status === "failed" ||
+                focusStep.status === "completed_with_errors" ||
+                focusStep.status === "not_started")) {
+            nextStep = focusStep;
+            kind = "graph_focus";
+        }
+    }
+    return {
+        current: (0, workflow_registry_1.getWorkflowStep)(currentStepId),
+        previous: prevStep ? resolveProjectStepHref(projectId, prevStep.pageRoute) : null,
+        next: nextStep ? resolveProjectStepHref(projectId, nextStep.pageRoute) : null,
+        nextName: nextStep?.name ?? null,
+        nextStepId: nextStep?.id ?? null,
+        dashboard: `/projects/${projectId}`,
+        kind,
+        unknownReason: null,
+    };
+}
+function pickNextDefinition(linearNext, focusId) {
+    if (linearNext === null) {
+        return null;
+    }
+    if (focusId === null) {
+        return { def: linearNext, kind: "linear" };
+    }
+    const focusDef = (0, workflow_registry_1.getWorkflowStep)(focusId);
+    if (focusDef === null) {
+        return { def: linearNext, kind: "linear" };
+    }
+    if (focusDef.order < linearNext.order) {
+        return { def: focusDef, kind: "graph_focus" };
+    }
+    return { def: linearNext, kind: "linear" };
+}
+/**
+ * Step URLs for a project. When `graph` is provided, the next target prefers an
+ * upstream blocking/focus step over naive linear order (fixes stuck “Implement” / #629).
+ */
+function getStepNavigation(projectId, currentStepId, graph) {
+    const currentStep = (0, workflow_registry_1.getWorkflowStep)(currentStepId);
+    const previousStep = (0, workflow_registry_1.getPreviousStep)(currentStepId);
+    const linearNextStep = (0, workflow_registry_1.getNextStep)(currentStepId);
+    if (graph === undefined) {
+        return {
+            current: currentStep,
+            previous: previousStep ? `/projects/${projectId}${previousStep.path}` : null,
+            next: linearNextStep ? `/projects/${projectId}${linearNextStep.path}` : null,
+            nextName: linearNextStep ? linearNextStep.title : null,
+            nextStepId: linearNextStep ? linearNextStep.id : null,
+            dashboard: `/projects/${projectId}`,
+            kind: "linear",
+            unknownReason: null,
+        };
+    }
+    if (graph.steps.length === 0) {
+        return {
+            current: currentStep,
+            previous: previousStep ? `/projects/${projectId}${previousStep.path}` : null,
+            next: linearNextStep ? `/projects/${projectId}${linearNextStep.path}` : null,
+            nextName: linearNextStep ? linearNextStep.title : null,
+            nextStepId: linearNextStep ? linearNextStep.id : null,
+            dashboard: `/projects/${projectId}`,
+            kind: "unknown",
+            unknownReason: UNKNOWN_NO_STEPS,
+        };
+    }
+    if (usesChannelSpineSteps(graph.steps)) {
+        return getChannelSpineNavigation(projectId, currentStepId, graph);
+    }
+    const focusId = resolveFocusId(graph);
+    const picked = pickNextDefinition(linearNextStep, focusId);
+    if (picked === null) {
+        return {
+            current: currentStep,
+            previous: previousStep ? `/projects/${projectId}${previousStep.path}` : null,
+            next: null,
+            nextName: null,
+            nextStepId: null,
+            dashboard: `/projects/${projectId}`,
+            kind: "linear",
+        };
+    }
+    return {
+        current: currentStep,
+        previous: previousStep ? `/projects/${projectId}${previousStep.path}` : null,
+        next: `/projects/${projectId}${picked.def.path}`,
+        nextName: picked.def.title,
+        nextStepId: picked.def.id,
+        dashboard: `/projects/${projectId}`,
+        kind: picked.kind,
+        unknownReason: null,
+    };
+}

package/dist/marketing/acquisition-landing-matrix.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Paid acquisition landing paths — SSOT for readiness probes and campaign final URLs.
+ * @see .cursor/plans/community-movie/google-ads-acquisition-spine.txt
+ */
+export declare const COMMUNITY_MOVIE_ACQUISITION_CAMPAIGN_THEMES: readonly ["cinematic_worlds", "ai_filmmaking", "atmospheric_storytelling", "collaborative_storytelling", "studio_join"];
+export type CommunityMovieAcquisitionCampaignTheme = (typeof COMMUNITY_MOVIE_ACQUISITION_CAMPAIGN_THEMES)[number];
+export declare const COMMUNITY_MOVIE_ACQUISITION_LANDING_PATHS: readonly [{
+    readonly path: "/start";
+    readonly campaignTheme: "studio_join";
+    readonly primaryCta: "/join/free";
+}, {
+    readonly path: "/join/free";
+    readonly campaignTheme: "studio_join";
+    readonly primaryCta: "/join/free";
+}, {
+    readonly path: "/worlds/aves-de-venecia";
+    readonly campaignTheme: "cinematic_worlds";
+    readonly worldSlug: "aves-de-venecia";
+    readonly primaryCta: "/join/free";
+}, {
+    readonly path: "/worlds/gearhaven";
+    readonly campaignTheme: "cinematic_worlds";
+    readonly worldSlug: "gearhaven";
+    readonly primaryCta: "/join/free";
+}, {
+    readonly path: "/worlds/aokujima";
+    readonly campaignTheme: "atmospheric_storytelling";
+    readonly worldSlug: "aokujima";
+    readonly primaryCta: "/join/free";
+}, {
+    readonly path: "/create-worlds";
+    readonly campaignTheme: "cinematic_worlds";
+    readonly primaryCta: "/app/worlds/submit";
+}, {
+    readonly path: "/ai-filmmaking";
+    readonly campaignTheme: "ai_filmmaking";
+    readonly primaryCta: "/join/free";
+}, {
+    readonly path: "/collaborative-storytelling";
+    readonly campaignTheme: "collaborative_storytelling";
+    readonly primaryCta: "/challenges";
+}, {
+    readonly path: "/join-the-studio";
+    readonly campaignTheme: "studio_join";
+    readonly primaryCta: "/join/free";
+}];

package/dist/marketing/acquisition-landing-matrix.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Paid acquisition landing paths — SSOT for readiness probes and campaign final URLs.
+ * @see .cursor/plans/community-movie/google-ads-acquisition-spine.txt
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMUNITY_MOVIE_ACQUISITION_LANDING_PATHS = exports.COMMUNITY_MOVIE_ACQUISITION_CAMPAIGN_THEMES = void 0;
+exports.COMMUNITY_MOVIE_ACQUISITION_CAMPAIGN_THEMES = [
+    'cinematic_worlds',
+    'ai_filmmaking',
+    'atmospheric_storytelling',
+    'collaborative_storytelling',
+    'studio_join',
+];
+exports.COMMUNITY_MOVIE_ACQUISITION_LANDING_PATHS = [
+    {
+        path: '/start',
+        campaignTheme: 'studio_join',
+        primaryCta: '/join/free',
+    },
+    {
+        path: '/join/free',
+        campaignTheme: 'studio_join',
+        primaryCta: '/join/free',
+    },
+    {
+        path: '/worlds/aves-de-venecia',
+        campaignTheme: 'cinematic_worlds',
+        worldSlug: 'aves-de-venecia',
+        primaryCta: '/join/free',
+    },
+    {
+        path: '/worlds/gearhaven',
+        campaignTheme: 'cinematic_worlds',
+        worldSlug: 'gearhaven',
+        primaryCta: '/join/free',
+    },
+    {
+        path: '/worlds/aokujima',
+        campaignTheme: 'atmospheric_storytelling',
+        worldSlug: 'aokujima',
+        primaryCta: '/join/free',
+    },
+    {
+        path: '/create-worlds',
+        campaignTheme: 'cinematic_worlds',
+        primaryCta: '/app/worlds/submit',
+    },
+    {
+        path: '/ai-filmmaking',
+        campaignTheme: 'ai_filmmaking',
+        primaryCta: '/join/free',
+    },
+    {
+        path: '/collaborative-storytelling',
+        campaignTheme: 'collaborative_storytelling',
+        primaryCta: '/challenges',
+    },
+    {
+        path: '/join-the-studio',
+        campaignTheme: 'studio_join',
+        primaryCta: '/join/free',
+    },
+];