@hypit/hypit 0.0.1 → 0.1.0

package/packages/narrative/src/schema.ts

@@ -0,0 +1,89 @@
+import type { ValueSchema } from "@hypit/protocol";
+
+const string = { kind: "string", minLength: 1 } as const;
+const integer = { kind: "number", integer: true, minimum: 0 } as const;
+const object = (
+  fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>,
+): ValueSchema => ({ kind: "object", fields });
+const semanticAnchor: ValueSchema = { kind: "oneOf", variants: [
+  object({
+    id: { schema: { kind: "literal", value: "program:start" } },
+    kind: { schema: { kind: "literal", value: "program-start" } },
+  }),
+  object({
+    id: { schema: string }, kind: { schema: { kind: "string", enum: ["segment-start", "segment-end"] } },
+    segmentId: { schema: string },
+  }),
+  object({
+    id: { schema: string }, kind: { schema: { kind: "string", enum: ["token-start", "token-end"] } },
+    segmentId: { schema: string }, tokenId: { schema: string },
+  }),
+  object({
+    id: { schema: { kind: "literal", value: "program:end" } },
+    kind: { schema: { kind: "literal", value: "program-end" } },
+  }),
+] };
+export const narrativeSchema: ValueSchema = object({
+  id: { schema: string },
+  segments: { schema: { kind: "array", minItems: 1, items: object({
+    id: { schema: string }, startAnchorId: { schema: string },
+    endAnchorId: { schema: string }, tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },
+  }) } },
+  tokens: { schema: { kind: "array", items: object({
+    id: { schema: string }, segmentId: { schema: string },
+    startAnchorId: { schema: string }, endAnchorId: { schema: string },
+    text: { schema: string }, normalized: { schema: string },
+  }) } },
+  turns: { schema: { kind: "array", items: object({
+    id: { schema: string }, segmentId: { schema: string }, role: { schema: string, optional: true },
+    tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },
+  }) } },
+  selections: { schema: { kind: "array", items: object({
+    id: { schema: string }, startAnchorId: { schema: string }, endAnchorId: { schema: string },
+  }) } },
+  moments: { schema: { kind: "array", items: object({
+    id: { schema: string }, anchorId: { schema: string },
+  }) } },
+  semanticIndex: { schema: object({
+
+    anchors: { schema: { kind: "array", minItems: 2, items: semanticAnchor } },
+  }) },
+});
+
+export const narrativeExcerptSchema: ValueSchema = object({
+  narrativeId: { schema: string },
+  kind: { schema: { kind: "literal", value: "segment" } }, id: { schema: string },
+  tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },
+});
+const captionDisplayWord = object({
+  id: { schema: string }, unitId: { schema: string }, segmentId: { schema: string },
+  turnId: { schema: string }, role: { schema: string, optional: true }, text: { schema: string },
+  attributes: { schema: { kind: "array", items: object({
+    name: { schema: string },
+    value: { schema: { kind: "oneOf", variants: [string, { kind: "number" }, { kind: "boolean" }] } },
+  }) } },
+});
+const captionAlignmentUnit = object({
+  id: { schema: string }, segmentId: { schema: string },
+  turnId: { schema: string }, role: { schema: string, optional: true },
+  wordIds: { schema: { kind: "array", minItems: 1, items: string } },
+  sourceTokenIds: { schema: { kind: "array", minItems: 1, items: string } },
+});
+const captionCueBreak = object({ afterUnitId: { schema: string } });
+export const captionDocumentSchema: ValueSchema = object({
+  narrativeId: { schema: string },
+  id: { schema: string },
+  units: { schema: { kind: "array", items: captionAlignmentUnit } },
+  words: { schema: { kind: "array", items: captionDisplayWord } },
+  cueBreaks: { schema: { kind: "array", items: captionCueBreak } },
+});
+export const narrativeMomentSchema: ValueSchema = object({
+  narrativeId: { schema: string },
+  id: { schema: string },
+  anchorId: { schema: string },
+});
+export const narrativeSelectionSchema: ValueSchema = object({
+  narrativeId: { schema: string },
+  id: { schema: string },
+  startAnchorId: { schema: string }, endAnchorId: { schema: string },
+});

package/packages/narrative/src/types.ts

@@ -0,0 +1,141 @@
+export type NarrativeSegment = {
+  readonly id: string;
+  readonly startAnchorId: string;
+  readonly endAnchorId: string;
+  readonly tokenStart: number;
+  readonly tokenEndExclusive: number;
+};
+
+export type NarrativeToken = {
+  readonly id: string;
+  readonly segmentId: string;
+  readonly startAnchorId: string;
+  readonly endAnchorId: string;
+  readonly text: string;
+  readonly normalized: string;
+};
+
+export type NarrativeTurn = {
+  readonly id: string;
+  readonly segmentId: string;
+  readonly role?: string;
+  readonly tokenStart: number;
+  readonly tokenEndExclusive: number;
+};
+
+export type NarrativeSelection = {
+  readonly id: string;
+  /** The exact semantic anchors chosen by the author Surface's affinity syntax. */
+  readonly startAnchorId: string;
+  readonly endAnchorId: string;
+};
+
+/** One explicitly authored semantic window, independently referenceable by graph edges. */
+export type NarrativeSelectionRef = NarrativeSelection & {
+  /** Author-visible `<script id>` that owns this independently exported Selection. */
+  readonly narrativeId: string;
+};
+
+export type NarrativeMoment = {
+  readonly id: string;
+  /** The exact semantic anchor chosen by the author Surface's affinity syntax. */
+  readonly anchorId: string;
+};
+
+/** One explicitly authored semantic instant, independently referenceable by graph edges. */
+export type NarrativeMomentRef = NarrativeMoment & {
+  /** Author-visible `<script id>` that owns this independently exported Moment. */
+  readonly narrativeId: string;
+};
+
+/** One author-visible word surface. Punctuation owned by the surface is preserved. */
+export type CaptionDisplayWord = {
+  readonly id: string;
+  readonly unitId: string;
+  readonly segmentId: string;
+  readonly turnId: string;
+  readonly role?: string;
+  readonly text: string;
+  /** Reserved for Script-native word attributes; empty until an inline Mark is authored. */
+  readonly attributes: readonly CaptionWordAttribute[];
+};
+
+export type CaptionWordAttributeValue = string | number | boolean;
+
+export type CaptionWordAttribute = {
+  readonly name: string;
+  readonly value: CaptionWordAttributeValue;
+};
+
+/** The smallest author-declared N:M display-to-speech correspondence unit. */
+export type CaptionAlignmentUnit = {
+  readonly id: string;
+  readonly segmentId: string;
+  readonly turnId: string;
+  readonly role?: string;
+  readonly wordIds: readonly string[];
+  /** Speech tokens are retained here so Caption can project a Narrative Selection without frames. */
+  readonly sourceTokenIds: readonly string[];
+};
+
+export type CaptionCueBreak = {
+  /** The Cue boundary is after this complete Alignment Unit. */
+  readonly afterUnitId: string;
+};
+
+/** Complete Script-owned Caption truth. It contains no frame or measured timing facts. */
+export type CaptionDocument = {
+  /** Author-visible `<script id>` that owns this caption projection. */
+  readonly narrativeId: string;
+  readonly id: string;
+  readonly units: readonly CaptionAlignmentUnit[];
+  readonly words: readonly CaptionDisplayWord[];
+  readonly cueBreaks: readonly CaptionCueBreak[];
+};
+
+export type SemanticAnchor =
+  | {
+      readonly id: "program:start";
+      readonly kind: "program-start";
+      readonly segmentId?: never;
+      readonly tokenId?: never;
+    }
+  | {
+      readonly id: "program:end";
+      readonly kind: "program-end";
+      readonly segmentId?: never;
+      readonly tokenId?: never;
+    }
+  | {
+      readonly id: string;
+      readonly kind: "segment-start" | "token-start" | "token-end" | "segment-end";
+      readonly segmentId: string;
+      readonly tokenId?: string;
+    };
+
+export type Narrative = {
+  /** Author-visible `<script id>`; every exported semantic view retains it. */
+  readonly id: string;
+  readonly segments: readonly NarrativeSegment[];
+  readonly tokens: readonly NarrativeToken[];
+  readonly turns: readonly NarrativeTurn[];
+  readonly selections: readonly NarrativeSelection[];
+  readonly moments: readonly NarrativeMoment[];
+  readonly semanticIndex: {
+    readonly anchors: readonly SemanticAnchor[];
+  };
+};
+
+/**
+ * One author-selected contiguous excerpt. Script is one possible producer;
+ * generation and speech packages consume this shared value without importing
+ * Script's parser or source representation.
+ */
+export type NarrativeExcerpt = {
+  readonly kind: "segment";
+  /** Author-visible `<script id>` that owns this Segment. */
+  readonly narrativeId: string;
+  readonly id: string;
+  readonly tokenStart: number;
+  readonly tokenEndExclusive: number;
+};

package/packages/package-loader-node/README.md

@@ -0,0 +1,23 @@
+# `@hypit/package-loader-node`
+
+Loads installed Hypit packages selected by source discovery or a Runtime Profile.
+
+The user's package manager owns installation, versions and package bytes. This loader resolves only
+the requested packages. An implementation package selected by Source discovery or a Runtime
+Profile may expose `hypit.activation`; the loader imports that entry and validates the contribution
+boundary consumed by Hypit. It never scans the dependency tree for plugins and is not a package
+manager or registry.
+
+A data-only package may instead expose an exact Source subpath through ordinary package `exports`.
+The Host can resolve that one requested file without importing `hypit.activation` or granting the
+package executable authority. Package-internal relative Sources and assets remain confined to the
+package root. Executable activation and Source-data lookup are deliberately separate operations.
+
+Module dependencies declared by selected packages are loaded from ordinary installed dependencies.
+Syntax, components and Runtime facets remain inert until a matching Host ABI consumes them.
+
+Physical lookup distinguishes package identity, ESM imports, package resources and npm executables.
+It does not use a CommonJS root export as evidence that a package is installed: CLI-only,
+import-only and resource-only packages are valid. The active Distribution owns `@hypit/*`;
+Distribution code may use upstream dependencies from the machine npm home, while project packages
+continue to resolve their own dependencies from the project.

package/packages/package-loader-node/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@hypit/package-loader-node",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/host": "workspace:*",
+    "@hypit/protocol": "workspace:*"
+  }
+}

package/packages/package-loader-node/src/contribution.ts

@@ -0,0 +1,97 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+
+import type {
+  LoadedComponentPackage,
+  LoadedPackage,
+  NodeModuleContribution,
+  NodePackageContribution,
+} from "./types.js";
+
+function assertPackage(value: NodePackageContribution): void {
+  if (value.format !== "hypit.node-package@1") {
+    throw new Error("Node package contribution has an unsupported format");
+  }
+  for (const facet of value.hostFacets ?? []) {
+    if (facet.abi.trim().length === 0) throw new Error("Node package contribution has an empty Host facet ABI");
+    const offers = facet.offers ?? [];
+    if (offers.some((item) => item.trim().length === 0)) {
+      throw new Error(`Node package contribution has an empty logical name for Host facet ${facet.abi}`);
+    }
+    if (new Set(offers).size !== offers.length) {
+      throw new Error(`Node package contribution repeats a logical name for Host facet ${facet.abi}`);
+    }
+  }
+}
+
+function facetKey(
+  ref: { readonly module: { readonly name: string; readonly version: string }; readonly name: string },
+): string {
+  return `${ref.module.name}@${ref.module.version}#${ref.name}`;
+}
+
+/** Collect declarative modules and executable component implementations from loaded packages. */
+export function collectNodePackageComponents(
+  packages: readonly NodePackageContribution[],
+): readonly ComponentPackage[] {
+  const manifests = new Map<string, NodeModuleContribution>();
+  const moduleSpecifiers = new Map<string, string>();
+  const components: ComponentPackage[] = [];
+  const producers = new Set<string>();
+  const validators = new Set<string>();
+  const declarations = new Set<string>();
+  for (const item of packages) {
+    assertPackage(item);
+    for (const module of item.modules ?? []) {
+      const key = `${module.manifest.name}@${module.manifest.version}`;
+      if (manifests.has(key)) throw new Error(`Node packages repeat Module ${key}`);
+      for (const specifier of new Set([key, ...(module.specifiers ?? [])])) {
+        if (specifier.trim().length === 0) throw new Error(`${key} declares an empty Module specifier`);
+        const owner = moduleSpecifiers.get(specifier);
+        if (owner !== undefined) throw new Error(`Module specifier ${specifier} is already bound to ${owner}`);
+        moduleSpecifiers.set(specifier, key);
+      }
+      manifests.set(key, module);
+      for (const producer of module.manifest.producers) {
+        declarations.add(`${key}#producer:${producer.name}`);
+      }
+      for (const type of module.manifest.types) {
+        declarations.add(`${key}#type:${type.name}`);
+      }
+    }
+    for (const component of item.components ?? []) {
+      components.push(component);
+      for (const producer of component.producers ?? []) {
+        const key = facetKey(producer.producer);
+        if (producers.has(key)) throw new Error(`Node packages repeat Producer facet ${key}`);
+        producers.add(key);
+      }
+      for (const validator of component.validators ?? []) {
+        const key = facetKey(validator.type);
+        if (validators.has(key)) throw new Error(`Node packages repeat Type Validator facet ${key}`);
+        validators.add(key);
+      }
+    }
+  }
+  for (const component of components) {
+    for (const facet of component.producers ?? []) {
+      const key = `${facet.producer.module.name}@${facet.producer.module.version}#producer:${facet.producer.name}`;
+      if (!declarations.has(key)) throw new Error(`Module ${facet.producer.module.name} implements undeclared Producer ${facetKey(facet.producer)}`);
+    }
+    for (const facet of component.validators ?? []) {
+      const key = `${facet.type.module.name}@${facet.type.module.version}#type:${facet.type.name}`;
+      if (!declarations.has(key)) throw new Error(`Module ${facet.type.module.name} validates undeclared Type ${facetKey(facet.type)}`);
+    }
+  }
+  return components;
+}
+
+/** Validate a loaded selection while preserving the physical owner of every Component package. */
+export function collectLoadedNodePackageComponents(
+  packages: readonly LoadedPackage[],
+): readonly LoadedComponentPackage[] {
+  collectNodePackageComponents(packages.map((item) => item.contribution));
+  return packages.map((item) => ({
+    specifier: item.specifier,
+    components: item.contribution.components ?? [],
+  }));
+}

package/packages/package-loader-node/src/distribution-resolution.ts

@@ -0,0 +1,146 @@
+import { registerHooks } from "node:module";
+import { join, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+import {
+  distributionPackageDirectory,
+  setActiveDistributionPackageRoots,
+  setActiveExternalPackageRoots,
+} from "./location.js";
+
+let installed: readonly string[] = [];
+let externalInstalled: readonly string[] = [];
+
+function packageAddress(specifier: string): { readonly name: string; readonly subpath: string } | undefined {
+  const parts = specifier.split("/");
+  if (specifier.startsWith("@")) {
+    if (parts.length < 2) return undefined;
+    return { name: `${parts[0]}/${parts[1]}`, subpath: parts.slice(2).join("/") };
+  }
+  return { name: parts[0]!, subpath: parts.slice(1).join("/") };
+}
+
+function barePackageSpecifier(specifier: string): boolean {
+  return !specifier.startsWith(".")
+    && !specifier.startsWith("/")
+    && !specifier.startsWith("#")
+    && !specifier.includes(":");
+}
+
+function distributionPackageEntry(root: string, specifier: string): string | undefined {
+  const address = packageAddress(specifier);
+  if (address === undefined) return undefined;
+  const packageRoot = distributionPackageDirectory(root, address.name);
+  if (packageRoot === undefined) return undefined;
+  const manifestPath = join(packageRoot, "package.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+    readonly name?: string;
+    readonly exports?: string | Readonly<Record<string, string>>;
+  };
+  if (manifest.name !== address.name) return undefined;
+  const key = address.subpath.length === 0 ? "." : `./${address.subpath}`;
+  const declared = typeof manifest.exports === "string"
+    ? (key === "." ? manifest.exports : undefined)
+    : manifest.exports?.[key];
+  return declared === undefined ? undefined : resolve(packageRoot, declared);
+}
+
+function distributionPublicEntry(root: string, specifier: string): string | undefined {
+  const address = packageAddress(specifier);
+  if (address === undefined) return undefined;
+  const manifestPath = join(root, "package.json");
+  if (!existsSync(manifestPath)) return undefined;
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+    readonly name?: string;
+    readonly exports?: Readonly<Record<string, string | {
+      readonly import?: string;
+      readonly default?: string;
+    }>>;
+  };
+  if (manifest.name !== address.name) return undefined;
+  const declared = manifest.exports?.[address.subpath.length === 0 ? "." : `./${address.subpath}`];
+  const target = typeof declared === "string" ? declared : declared?.import ?? declared?.default;
+  return target === undefined ? undefined : resolve(root, target);
+}
+
+/** Resolve one import owned by an explicit Hypit Distribution. */
+export function resolveDistributionPackageImport(root: string, specifier: string): string | undefined {
+  if (specifier.startsWith("@hypit/")) {
+    return distributionPublicEntry(resolve(root), specifier) ?? distributionPackageEntry(resolve(root), specifier);
+  }
+  return undefined;
+}
+
+/**
+ * Let external project activations import official packages from a read-only Distribution checkout.
+ * The @hypit namespace belongs to the active Distribution and cannot be shadowed by project installs.
+ */
+export function installDistributionPackageResolution(roots: readonly string[]): void {
+  const next = roots.map((root) => resolve(root));
+  if (next.every((root, index) => root === installed[index]) && next.length === installed.length) return;
+  if (installed.length > 0) throw new Error("Distribution package roots cannot change inside one Host process");
+  installed = next;
+  setActiveDistributionPackageRoots(installed);
+  const rootUrls = installed.map((root) => pathToFileURL(`${root}/`).href);
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      if (specifier.startsWith("@hypit/")) {
+        // A contributor checkout may resolve through workspace links. An installed
+        // monolithic Distribution resolves from its own packages/services tree.
+        // Accept ordinary resolution only when its real target remains inside this
+        // Distribution; a project-local package with the same spelling may not shadow it.
+        try {
+          const found = nextResolve(specifier, context);
+          if (found.url.startsWith("file:") && rootUrls.some((root) => found.url.startsWith(root))) {
+            return found;
+          }
+        } catch {
+          // Try the explicit Distribution resolvers below.
+        }
+        for (const root of installed) {
+          const entry = resolveDistributionPackageImport(root, specifier);
+          if (entry !== undefined) return { url: pathToFileURL(entry).href, shortCircuit: true };
+        }
+        throw new Error(`Active Hypit Distribution does not provide ${specifier}`);
+      }
+      return nextResolve(specifier, context);
+    },
+  });
+}
+
+/**
+ * Fall back to the machine npm home for upstream packages that are not part of
+ * the Distribution or the current project. Project resolution always wins;
+ * the @hypit namespace always remains Distribution-owned.
+ */
+export function installExternalPackageResolution(roots: readonly string[]): void {
+  const next = roots.map((root) => resolve(root));
+  if (next.every((root, index) => root === externalInstalled[index])
+    && next.length === externalInstalled.length) return;
+  if (externalInstalled.length > 0) {
+    throw new Error("External package roots cannot change inside one Host process");
+  }
+  externalInstalled = next;
+  setActiveExternalPackageRoots(externalInstalled);
+  const parentUrls = externalInstalled.map((root) => pathToFileURL(join(root, "__hypit_external__.mjs")).href);
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      if (specifier.startsWith("@hypit/") || !barePackageSpecifier(specifier)) {
+        return nextResolve(specifier, context);
+      }
+      try {
+        return nextResolve(specifier, context);
+      } catch (original) {
+        for (const parentURL of parentUrls) {
+          try {
+            return nextResolve(specifier, { ...context, parentURL });
+          } catch {
+            // Try the next machine package root before preserving Node's error.
+          }
+        }
+        throw original;
+      }
+    },
+  });
+}

package/packages/package-loader-node/src/index.ts

@@ -0,0 +1,27 @@
+export {
+  collectLoadedNodePackageComponents,
+  collectNodePackageComponents,
+} from "./contribution.js";
+export {
+  loadNodePackageSelection,
+  NodePackageSelectionMissingError,
+  physicalPackageName,
+  distributionExternalPackageRequirements,
+} from "./loader.js";
+export {
+  installDistributionPackageResolution,
+  installExternalPackageResolution,
+  resolveDistributionPackageImport,
+} from "./distribution-resolution.js";
+export {
+  locateNodePackage,
+  resolveNodePackageExecutable,
+  resolveNodePackageResource,
+  resolveNodePackageSource,
+} from "./location.js";
+export type {
+  LocatedNodePackage,
+  LocatedNodePackageSource,
+  LocateNodePackageOptions,
+} from "./location.js";
+export type * from "./types.js";