@soulcraft/cor 3.0.0-rc.1

package/dist/cli.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * cor CLI — license management for @soulcraft/cor
+ *
+ * Commands:
+ *   activate <code-or-key>   Write activation code or JWT to .soulcraft.json
+ *   status                   Show current license configuration and validation result
+ *   deactivate               Remove the cor license from .soulcraft.json
+ *   help                     Print this help text
+ */
+import { join } from 'node:path';
+import { readConfig, writeConfig, isShortCode, exchangeShortCode, readLicenseToken } from './license.js';
+import { SHORT_CODE_PATTERN, CONFIG_FILE } from './license/constants.js';
+const JWT_PREFIX = 'sc_cor_';
+// Legacy prefix still accepted during the cortex→cor rename transition.
+const LEGACY_JWT_PREFIX = 'sc_cortex_';
+const isJwtToken = (s) => s.startsWith(JWT_PREFIX) || s.startsWith(LEGACY_JWT_PREFIX);
+/** Read the license value from either the new `cor` key or the legacy `cortex` key. */
+const readLicenseValue = (config) => config.cor ?? config.cortex;
+/**
+ * Determine the raw license value and which source provided it, using the same
+ * cache→env→file order as readLicenseToken(). We do NOT consult the in-memory
+ * cache here: a fresh `cor status` process has no heartbeat-populated cache, so
+ * the externally-observable sources are the env var and the config file.
+ */
+function resolveLicenseSource(config) {
+    // Env var wins over the file (matches readLicenseToken). Trimmed because
+    // secrets managers and `$(cat …)` often append a trailing newline.
+    const corEnv = process.env.COR_LICENSE_KEY?.trim();
+    if (corEnv)
+        return { source: 'env', value: corEnv, envVarName: 'COR_LICENSE_KEY' };
+    const legacyEnv = process.env.CORTEX_LICENSE_KEY?.trim();
+    if (legacyEnv)
+        return { source: 'env', value: legacyEnv, envVarName: 'CORTEX_LICENSE_KEY' };
+    const fileValue = readLicenseValue(config);
+    if (fileValue)
+        return { source: 'file', value: fileValue };
+    return { source: 'none', value: undefined };
+}
+function printHelp() {
+    console.log(`
+cor — license management for @soulcraft/cor
+
+USAGE
+  npx @soulcraft/cor <command> [args]
+
+COMMANDS
+  activate <code-or-key>   Activate with a short code (CO-XXXX-XXXX) or JWT
+  status                   Show current license status
+  deactivate               Remove the cor license key
+  help                     Print this help text
+
+EXAMPLES
+  npx @soulcraft/cor activate CO-7F3A-9B2D
+  npx @soulcraft/cor status
+  npx @soulcraft/cor deactivate
+
+NOTES
+  Activation writes to ${CONFIG_FILE} in the current directory.
+  Commit this file — it deploys with your app and works in dev/staging/prod.
+  Get your activation code at https://soulcraft.com/account
+`.trimStart());
+}
+async function cmdActivate(arg) {
+    if (!arg) {
+        console.error('Error: activate requires a code or key argument');
+        console.error('  Usage: npx @soulcraft/cor activate <code-or-key>');
+        console.error('  Example: npx @soulcraft/cor activate CO-7F3A-9B2D');
+        process.exit(1);
+    }
+    const isCode = isShortCode(arg);
+    const isJwt = isJwtToken(arg);
+    if (!isCode && !isJwt) {
+        console.error(`Error: invalid format — "${arg}"`);
+        console.error('');
+        console.error('Expected either:');
+        console.error(`  A short code matching ${SHORT_CODE_PATTERN} (e.g. CO-7F3A-9B2D)`);
+        console.error(`  A JWT starting with "${JWT_PREFIX}"`);
+        console.error('');
+        console.error('Get your activation code at https://soulcraft.com/account');
+        process.exit(1);
+    }
+    if (isCode) {
+        // Exchange the short code for a JWT first — write only the JWT to .soulcraft.json.
+        // The JWT validates offline, so the deployed app never needs to reach the exchange API.
+        process.stdout.write(`Exchanging ${arg} with soulcraft.com... `);
+        const jwt = await exchangeShortCode(arg);
+        if (!jwt) {
+            console.error('failed');
+            console.error('');
+            console.error('Could not exchange activation code. Check:');
+            console.error('  - Your code is correct at https://soulcraft.com/account');
+            console.error('  - This machine has outbound HTTPS access to soulcraft.com');
+            console.error('');
+            console.error('Tip: activate on a machine with internet access, then commit .soulcraft.json');
+            process.exit(1);
+        }
+        console.log('ok');
+        await writeConfig({ cor: jwt });
+        console.log(`\nActivated. ${CONFIG_FILE} written — commit it to your repository.`);
+    }
+    else {
+        // Direct JWT — write immediately; validates offline, no exchange needed.
+        await writeConfig({ cor: arg });
+        console.log(`License key written to ${CONFIG_FILE} — commit it to your repository.`);
+    }
+}
+async function cmdStatus() {
+    // Resolve the same way the runtime does (cache→env→file), so an env-var-only
+    // deploy (COR_LICENSE_KEY set, no .soulcraft.json) reports as configured.
+    const config = await readConfig();
+    const { source, value, envVarName } = resolveLicenseSource(config);
+    if (source === 'none' || !value) {
+        console.log('No Soulcraft Cor license configured.');
+        console.log(`Add one with: npx @soulcraft/cor activate CO-XXXX-XXXX`);
+        console.log('Or set the COR_LICENSE_KEY environment variable.');
+        console.log('Or visit https://soulcraft.com/account for your activation code.');
+        return;
+    }
+    const isCode = isShortCode(value);
+    const isJwt = isJwtToken(value);
+    // Report which source supplied the value — env var vs .soulcraft.json.
+    if (source === 'env') {
+        console.log(`Source: ${envVarName} environment variable`);
+    }
+    else {
+        console.log(`Source: ${CONFIG_FILE}`);
+    }
+    console.log(`  key:  ${isCode ? value : value.slice(0, 20) + '...'}`);
+    console.log(`  type: ${isCode ? 'activation code' : isJwt ? 'JWT' : 'unknown format'}`);
+    console.log('');
+    if (isCode) {
+        // Use the runtime resolver so short-code exchange and caching match exactly
+        // what validateLicense() would do for this same value.
+        process.stdout.write('Exchanging short code with soulcraft.com... ');
+        const jwt = await readLicenseToken();
+        if (!jwt) {
+            console.log('failed (server unreachable or invalid code)');
+            console.log('Check your code at https://soulcraft.com/account');
+            return;
+        }
+        console.log('ok');
+        console.log('');
+        await printValidation(jwt);
+    }
+    else if (isJwt) {
+        await printValidation(value);
+    }
+    else {
+        console.log('Warning: unrecognized format — expected CO-XXXX-XXXX or sc_cor_...');
+    }
+}
+async function printValidation(token) {
+    try {
+        const { loadNativeModule, isNativeAvailable } = await import('./native/index.js');
+        if (!isNativeAvailable()) {
+            console.log('Native module unavailable — cannot validate locally.');
+            return;
+        }
+        const native = loadNativeModule();
+        const result = native.validateLicenseKey(token);
+        if (result.valid) {
+            console.log(`Status: valid`);
+            console.log(`  Tier:    ${result.tier}`);
+            console.log(`  Email:   ${result.email}`);
+            if (result.expiresAt > 0) {
+                const expiry = new Date(result.expiresAt * 1000).toISOString().split('T')[0];
+                console.log(`  Expires: ${expiry}`);
+            }
+            else {
+                console.log(`  Expires: never (internal)`);
+            }
+        }
+        else {
+            console.log(`Status: invalid`);
+            if (result.error)
+                console.log(`  Error: ${result.error}`);
+        }
+    }
+    catch {
+        console.log('Could not load native module for local validation.');
+    }
+}
+async function cmdDeactivate() {
+    const config = await readConfig();
+    if (!config.cor && !config.cortex) {
+        console.log('Nothing to deactivate — no cor license in .soulcraft.json');
+        return;
+    }
+    // Strip both the new `cor` key and the legacy `cortex` key.
+    const { cor: _c1, cortex: _c2, ...remaining } = config;
+    const remainingKeys = Object.keys(remaining);
+    if (remainingKeys.length === 0) {
+        // Remove the file entirely
+        const { unlink } = await import('node:fs/promises');
+        try {
+            await unlink(join(process.cwd(), CONFIG_FILE));
+        }
+        catch {
+            // Already gone
+        }
+        console.log(`Removed Soulcraft Cor license. ${CONFIG_FILE} deleted (was empty).`);
+    }
+    else {
+        // Write remaining keys directly — writeConfig merges, so we write the file ourselves
+        const { writeFile: _writeFile, rename: _rename } = await import('node:fs/promises');
+        const configPath = join(process.cwd(), CONFIG_FILE);
+        const tmpPath = `${configPath}.tmp`;
+        await _writeFile(tmpPath, JSON.stringify(remaining, null, 2) + '\n', 'utf-8');
+        await _rename(tmpPath, configPath);
+        console.log(`Removed Soulcraft Cor license from ${CONFIG_FILE}.`);
+    }
+}
+const [, , command, ...args] = process.argv;
+switch (command) {
+    case 'activate':
+        await cmdActivate(args[0]);
+        break;
+    case 'status':
+        await cmdStatus();
+        break;
+    case 'deactivate':
+        await cmdDeactivate();
+        break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+        printHelp();
+        break;
+    default:
+        console.error(`Unknown command: ${command}`);
+        console.error('Run "npx @soulcraft/cor help" for usage.');
+        process.exit(1);
+}
+//# sourceMappingURL=cli.js.map

package/dist/graph/GraphAccelerationAdapter.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @module graph/GraphAccelerationAdapter
+ * @description The `'graphAcceleration'` provider — cor's native graph
+ * engine behind brainy 8.0's optional {@link GraphAccelerationProvider}
+ * contract (ADR-006). When brainy feature-detects this provider, the
+ * public `brain.graph.*` surface (`subgraph` / `export`) and the
+ * `related()` / `find({ connected })` paths route here instead of brainy's
+ * pure-TS adjacency fallback.
+ *
+ * **It wraps the SAME native handle the `graphIndex` provider already
+ * holds** — never a second `NativeGraphAdjacencyIndex` (which would split
+ * state + double RAM). brainy's `activate(context)` hook has no storage and
+ * its provider factories are called with storage only (not the graphIndex
+ * instance), and the `graphAcceleration` value is feature-detected raw
+ * (the factory is never invoked with storage), so this adapter is
+ * registered at `activate()` time bound to a *resolver* that the
+ * `graphIndex` factory fills once it constructs the native engine. Until
+ * the engine is built + loaded, {@link isInitialized} reports `false` and
+ * brainy keeps serving graph ops from TS — the contract's safety valve, so
+ * a read is never routed here before the data is loaded.
+ *
+ * **Scope (cor 3.0 / brainy 8.0):** the full `GraphAccelerationProvider`
+ * surface — `traverse`, `edgesForNode`, the streaming cursor
+ * (`graphCursorOpen` / `graphCursorNext` / `graphCursorClose`), AND the Phase C
+ * analytics (`pageRank`, `connectedComponents`, `shortestPath`,
+ * `neighborhoodSample`, `topByDegree`). All five analytics ship together (the
+ * feature-detect anchors on `traverse` + `graphCursorOpen`, but brainy does not
+ * per-method-guard the analytics — a partial set would throw). **`shortestPath`
+ * is hops-only** — cor stores no edge weights, so the adapter refuses
+ * `weight: 'edge'` and brainy must serve weighted paths from TS.
+ *
+ * **Zero-copy decode:** native reads return columnar little-endian
+ * {@link Buffer}s; this adapter views each as the matching typed array over
+ * the same memory (no element-wise copy) on the little-endian hosts cor
+ * targets, falling back to a copy only on the (never-expected) misaligned
+ * Buffer. brainy resolves the u64 node/verb ints to UUIDs lazily.
+ *
+ * **Not applied here:** `excludeVisibility` (the graph index carries no
+ * node-visibility data — that lives in the metadata/vector layer; brainy
+ * applies visibility on reassembly) and `subtypes` (cor's traverse filters
+ * by verb-type index only). Both are dropped at this seam, matching Phase A
+ * `traverse`.
+ */
+import type { Subgraph, OpaqueIdSet, TraverseOptions, EdgesForNodeOptions, GraphCursorOptions, GraphCursorChunk, GraphCursorHandle, GraphScores, GraphCommunities, GraphPath, RankOptions, CommunitiesOptions, PathOptions, SampleOptions, MostConnectedOptions } from '@soulcraft/brainy/plugin';
+import type { GraphAdjacencyIndex } from './NativeGraphAdjacencyIndex.js';
+/**
+ * @description cor's `'graphAcceleration'` provider. Registered structurally
+ * (NOT via `implements GraphAccelerationProvider`, which would force the 5
+ * Phase-C analytics methods to exist) — brainy validates it at runtime via
+ * the two-anchor feature-detect (`traverse` + `graphCursorOpen`).
+ */
+export declare class GraphAccelerationAdapter {
+    private readonly resolveEngine;
+    /**
+     * @param resolveEngine - Resolver for the shared `graphIndex` provider
+     *   instance. Returns `undefined` until the `graphIndex` factory has
+     *   constructed the native engine; the adapter reports
+     *   {@link isInitialized} `false` until then so brainy doesn't route here.
+     */
+    constructor(resolveEngine: () => GraphAdjacencyIndex | undefined);
+    /** The shared native graph engine, or `undefined` before construction. */
+    private get engine();
+    /**
+     * `false` until the shared native graph engine is constructed AND has
+     * loaded its persisted state. brainy probes this before routing, so a
+     * read is never served from native before the data is present.
+     */
+    get isInitialized(): boolean;
+    /** Resolve the native instance or throw a clear error (defensive — brainy
+     * gates on {@link isInitialized}, so this should never fire in practice). */
+    private native;
+    /** Translate brainy's {@link TraverseOptions} to the native shape (drops
+     * `subtypes` / `excludeVisibility`, which this seam does not apply). */
+    private toNativeTraverse;
+    /**
+     * @description Bounded multi-hop expansion from `seeds` (entity ints or a
+     *   `find()` {@link OpaqueIdSet}), returning the reachable subgraph in one
+     *   native call.
+     * @param seeds - Start nodes as `bigint[]`, or an OpaqueIdSet envelope
+     *   (forwarded with no id materialization — the query→expand fusion).
+     * @param options - Depth, direction, verb-type filter, caps.
+     * @param generation - Optional as-of generation (omitted = now).
+     */
+    traverse(seeds: bigint[] | OpaqueIdSet, options: TraverseOptions, generation?: bigint): Promise<Subgraph>;
+    /**
+     * @description All edges incident to one node, both directions — a
+     *   depth-1 {@link traverse} from the single node.
+     * @param nodeInt - The node's interned entity int.
+     * @param options - Direction, verb-type filter, limit.
+     * @param generation - Optional as-of generation.
+     */
+    edgesForNode(nodeInt: bigint, options: EdgesForNodeOptions, generation?: bigint): Promise<Subgraph>;
+    /**
+     * @description Open a snapshot-consistent streaming walk of the whole
+     *   graph (or a seeded region), pinned to a generation. Returns a
+     *   TTL-bounded handle for {@link graphCursorNext} / {@link graphCursorClose}.
+     * @param options - Direction, projection, optional seeds / resume cursor.
+     * @param generation - Optional explicit as-of generation to pin.
+     */
+    graphCursorOpen(options: GraphCursorOptions, generation?: bigint): Promise<GraphCursorHandle>;
+    /**
+     * @description Pull the next chunk from an open cursor.
+     * @param handle - From {@link graphCursorOpen}.
+     * @param chunkSize - Target number of edges in this chunk.
+     * @throws An error whose message starts `SnapshotExpired:` if the handle
+     *   sat idle past its TTL — reopen with the last chunk's `cursor` to resume.
+     */
+    graphCursorNext(handle: GraphCursorHandle, chunkSize: number): Promise<GraphCursorChunk>;
+    /**
+     * @description Release an open cursor's pinned generation + server-side
+     *   state. Idempotent.
+     * @param handle - From {@link graphCursorOpen}.
+     */
+    graphCursorClose(handle: GraphCursorHandle): Promise<void>;
+    /**
+     * @description `rank` — importance/influence ranking over the visible graph.
+     *   Intent-level: cor implements it natively via PageRank (algorithm is the
+     *   provider's choice). `excludeVisibility` is dropped at this seam — brainy
+     *   post-filters (and renormalizes/re-top-Ks) on hydrate; the native rank is
+     *   over all nodes. (Renamed from `pageRank` for brainy rc.3 intent contract, #71.)
+     */
+    rank(options: RankOptions, generation?: bigint): Promise<GraphScores>;
+    /**
+     * @description `communities` — group related nodes. Intent-level: cor
+     *   implements it natively via connected components (`directed` → strong/SCC,
+     *   else weak). The labels are arbitrary-but-stable — only the partition is
+     *   meaningful; do not cache them as keys. (Renamed from `connectedComponents`, #71.)
+     */
+    communities(options: CommunitiesOptions, generation?: bigint): Promise<GraphCommunities>;
+    /**
+     * @description `path` — best route between two nodes. Intent-level: cor
+     *   implements hops natively. cor stores no edge weights, so `by: 'weight'` is
+     *   unsupported here — brainy serves least-weight paths from its TS fallback.
+     *   Returns `null` when unreachable. (Renamed from `shortestPath`; `weight` →
+     *   `by` for brainy rc.3, #71.)
+     * @throws If `options.by === 'weight'`.
+     */
+    path(fromInt: bigint, toInt: bigint, options: PathOptions, generation?: bigint): Promise<GraphPath | null>;
+    /**
+     * @description `sample` — deterministic, seeded bounded neighborhood sample for
+     *   dense-graph viz. Intent-level; cor implements it natively. (Renamed from
+     *   `neighborhoodSample`, #71.)
+     * @param seeds - `bigint[]` or a `find()` OpaqueIdSet.
+     */
+    sample(seeds: bigint[] | OpaqueIdSet, options: SampleOptions, generation?: bigint): Promise<Subgraph>;
+    /**
+     * @description `mostConnected` — the top-K most-connected nodes. Intent-level:
+     *   cor implements it natively via degree. `excludeVisibility` dropped at this
+     *   seam (brainy post-filters). (Renamed from `topByDegree`, #71.)
+     */
+    mostConnected(options: MostConnectedOptions, generation?: bigint): Promise<GraphScores>;
+}
+//# sourceMappingURL=GraphAccelerationAdapter.d.ts.map