@faicad/faijs 0.13.0

package/dist/fcstd/sketch-verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sketch-verify.d.ts","sourceRoot":"","sources":["../../src/fcstd/sketch-verify.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAiBvD,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,MAAM,CAazE;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,MAAM,EAAE,UAAU,EAAE,EACpB,EAAE,EAAE,MAAM,EACV,UAAU,CAAC,EAAE,MAAM,GAClB,aAAa,CASf"}

package/dist/fcstd/sketch-verify.js

@@ -0,0 +1,49 @@
+function anchorPoints(g) {
+    switch (g.kind) {
+        case 'point':
+            return [{ x: g.x, y: g.y }];
+        case 'line':
+            return [{ x: g.x1, y: g.y1 }, { x: g.x2, y: g.y2 }];
+        case 'circle':
+            return [{ x: g.cx, y: g.cy }];
+        case 'arc':
+            return [{ x: g.cx, y: g.cy }, { x: g.x1, y: g.y1 }, { x: g.x2, y: g.y2 }];
+        case 'ellipse':
+            return [{ x: g.cx, y: g.cy }];
+    }
+}
+/** Maximum anchor-point distance between two geometry lists (same indexing). */
+export function maxPointDistance(a, b) {
+    let max = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        const pa = anchorPoints(a[i]);
+        const pb = anchorPoints(b[i]);
+        const m = Math.min(pa.length, pb.length);
+        for (let k = 0; k < m; k++) {
+            const d = Math.hypot(pa[k].x - pb[k].x, pa[k].y - pb[k].y);
+            if (Number.isFinite(d) && d > max)
+                max = d;
+        }
+    }
+    return max;
+}
+/**
+ * Three-level downgrade (D3). L0 = solved & matches stored (delta <= T1).
+ * L1 = solver result kept but flagged, stored coords used instead.
+ * L2 = baked (unsupported geometry/constraints, external geometry).
+ */
+export function classifySketch(outcome, stored, t1, preBlocked) {
+    if (preBlocked)
+        return { level: 'L2', reason: preBlocked };
+    if (!outcome)
+        return { level: 'L2', reason: 'no-solver-result' };
+    if (!outcome.converged) {
+        return { level: 'L1', reason: outcome.reason ?? 'solve-failed' };
+    }
+    const maxDelta = maxPointDistance(outcome.geoms, stored);
+    if (maxDelta <= t1)
+        return { level: 'L0', maxDelta };
+    return { level: 'L1', reason: 'delta-exceeds-t1', maxDelta };
+}
+//# sourceMappingURL=sketch-verify.js.map

package/dist/fcstd/sketch-verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sketch-verify.js","sourceRoot":"","sources":["../../src/fcstd/sketch-verify.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * M3.5 — solved-vs-stored comparison (D2/V2).\n *\n * The on-disk coordinates ARE FreeCAD's last solution, so a correct pipeline\n * re-derives (nearly) the same geometry. maxPointDistance is the V2 metric;\n * its tolerance T1 is calibrated from the sample-set distribution, not\n * pre-set (plan §8).\n */\nimport type { SketchGeom } from './sketch-parse.js';\nimport type { SolveOutcome } from './sketch-solver.js';\n\nfunction anchorPoints(g: SketchGeom): { x: number; y: number }[] {\n  switch (g.kind) {\n    case 'point':\n      return [{ x: g.x, y: g.y }];\n    case 'line':\n      return [{ x: g.x1, y: g.y1 }, { x: g.x2, y: g.y2 }];\n    case 'circle':\n      return [{ x: g.cx, y: g.cy }];\n    case 'arc':\n      return [{ x: g.cx, y: g.cy }, { x: g.x1, y: g.y1 }, { x: g.x2, y: g.y2 }];\n    case 'ellipse':\n      return [{ x: g.cx, y: g.cy }];\n  }\n}\n\n/** Maximum anchor-point distance between two geometry lists (same indexing). */\nexport function maxPointDistance(a: SketchGeom[], b: SketchGeom[]): number {\n  let max = 0;\n  const n = Math.min(a.length, b.length);\n  for (let i = 0; i < n; i++) {\n    const pa = anchorPoints(a[i]!);\n    const pb = anchorPoints(b[i]!);\n    const m = Math.min(pa.length, pb.length);\n    for (let k = 0; k < m; k++) {\n      const d = Math.hypot(pa[k]!.x - pb[k]!.x, pa[k]!.y - pb[k]!.y);\n      if (Number.isFinite(d) && d > max) max = d;\n    }\n  }\n  return max;\n}\n\nexport interface SketchVerdict {\n  level: 'L0' | 'L1' | 'L2';\n  reason?: string;\n  /** max anchor distance between re-solved and stored geometry */\n  maxDelta?: number;\n}\n\n/**\n * Three-level downgrade (D3). L0 = solved & matches stored (delta <= T1).\n * L1 = solver result kept but flagged, stored coords used instead.\n * L2 = baked (unsupported geometry/constraints, external geometry).\n */\nexport function classifySketch(\n  outcome: SolveOutcome | undefined,\n  stored: SketchGeom[],\n  t1: number,\n  preBlocked?: string,\n): SketchVerdict {\n  if (preBlocked) return { level: 'L2', reason: preBlocked };\n  if (!outcome) return { level: 'L2', reason: 'no-solver-result' };\n  if (!outcome.converged) {\n    return { level: 'L1', reason: outcome.reason ?? 'solve-failed' };\n  }\n  const maxDelta = maxPointDistance(outcome.geoms, stored);\n  if (maxDelta <= t1) return { level: 'L0', maxDelta };\n  return { level: 'L1', reason: 'delta-exceeds-t1', maxDelta };\n}\n"]}

package/dist/fcstd/unpack.d.ts

@@ -0,0 +1,25 @@
+import { type Result } from '../vendored/brepjs/core/result.js';
+export interface FcstdMember {
+    /** path inside the ZIP, e.g. "Document.xml", "PartShape.brp" */
+    path: string;
+    bytes: Uint8Array;
+}
+export interface FcstdArchive {
+    members: Map<string, Uint8Array>;
+    /** advisory ZIP comment; may be empty (2/56 samples have empty comments) */
+    zipComment: string;
+}
+export type UnpackError = {
+    kind: 'not-zip';
+    message: string;
+} | {
+    kind: 'no-document-xml';
+    message: string;
+};
+/**
+ * Unpack an FCStd file. Only requirement: valid ZIP + root `Document.xml`.
+ */
+export declare function unpackFcstd(data: Uint8Array): Result<FcstdArchive, UnpackError>;
+/** UTF-8 text decode helper for XML members. */
+export declare function memberText(archive: FcstdArchive, path: string): string | undefined;
+//# sourceMappingURL=unpack.d.ts.map

package/dist/fcstd/unpack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unpack.d.ts","sourceRoot":"","sources":["../../src/fcstd/unpack.ts"],"names":[],"mappings":"AAUA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,mCAAmC,CAAC;AAEzE,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACjC,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,YAAY,EAAE,WAAW,CAAC,CAkB/E;AAiBD,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIlF"}

package/dist/fcstd/unpack.js

@@ -0,0 +1,55 @@
+/**
+ * M1.1 — FCStd container unpacking.
+ *
+ * Validation rules per plan §5.5.6 (corrected): a file is an FCStd iff it opens
+ * as a ZIP and contains `Document.xml` at its root. The ZIP comment is advisory
+ * only and must never cause rejection.
+ *
+ * faijs contract: unit mm, errors via Result (ok/err).
+ */
+import { unzipSync } from 'fflate';
+import { err, ok } from '../vendored/brepjs/core/result.js';
+/**
+ * Unpack an FCStd file. Only requirement: valid ZIP + root `Document.xml`.
+ */
+export function unpackFcstd(data) {
+    let entries;
+    try {
+        entries = unzipSync(data);
+    }
+    catch (e) {
+        return err({
+            kind: 'not-zip',
+            message: `cannot open as ZIP: ${e instanceof Error ? e.message : String(e)}`,
+        });
+    }
+    if (!('Document.xml' in entries)) {
+        return err({ kind: 'no-document-xml', message: 'root Document.xml not found in ZIP' });
+    }
+    // fflate does not expose the raw ZIP comment through unzipSync; read it
+    // directly from the EOCD record (22 bytes from end when comment is empty,
+    // else longer). Advisory only — never used for validation.
+    const comment = readZipComment(data) ?? '';
+    return ok({ members: new Map(Object.entries(entries)), zipComment: comment });
+}
+function readZipComment(data) {
+    // scan for EOCD signature 0x06054b50 from the end
+    for (let i = data.length - 22; i >= Math.max(0, data.length - 22 - 65535); i--) {
+        if (data[i] === 0x50 && data[i + 1] === 0x4b && data[i + 2] === 0x05 && data[i + 3] === 0x06) {
+            const len = data[i + 20] | (data[i + 21] << 8);
+            const start = i + 22;
+            if (start + len > data.length)
+                return null;
+            return new TextDecoder('latin1').decode(data.subarray(start, start + len));
+        }
+    }
+    return null;
+}
+/** UTF-8 text decode helper for XML members. */
+export function memberText(archive, path) {
+    const bytes = archive.members.get(path);
+    if (!bytes)
+        return undefined;
+    return new TextDecoder('utf-8').decode(bytes);
+}
+//# sourceMappingURL=unpack.js.map

package/dist/fcstd/unpack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unpack.js","sourceRoot":"","sources":["../../src/fcstd/unpack.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,MAAM,mCAAmC,CAAC;AAkBzE;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,IAAI,OAAmC,CAAC;IACxC,IAAI,CAAC;QACH,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,GAAG,CAAC;YACT,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,uBAAuB,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;SAC7E,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,CAAC,cAAc,IAAI,OAAO,CAAC,EAAE,CAAC;QACjC,OAAO,GAAG,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,oCAAoC,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,wEAAwE;IACxE,0EAA0E;IAC1E,2DAA2D;IAC3D,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAC3C,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,cAAc,CAAC,IAAgB;IACtC,kDAAkD;IAClD,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/E,IACE,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,EACxF,CAAC;YACD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,GAAG,EAAE,CAAE,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAE,IAAI,CAAC,CAAC,CAAC;YACjD,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,CAAC;YACrB,IAAI,KAAK,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM;gBAAE,OAAO,IAAI,CAAC;YAC3C,OAAO,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC;QAC7E,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,UAAU,CAAC,OAAqB,EAAE,IAAY;IAC5D,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC","sourcesContent":["/**\n * M1.1 — FCStd container unpacking.\n *\n * Validation rules per plan §5.5.6 (corrected): a file is an FCStd iff it opens\n * as a ZIP and contains `Document.xml` at its root. The ZIP comment is advisory\n * only and must never cause rejection.\n *\n * faijs contract: unit mm, errors via Result (ok/err).\n */\nimport { unzipSync } from 'fflate';\nimport { err, ok, type Result } from '../vendored/brepjs/core/result.js';\n\nexport interface FcstdMember {\n  /** path inside the ZIP, e.g. \"Document.xml\", \"PartShape.brp\" */\n  path: string;\n  bytes: Uint8Array;\n}\n\nexport interface FcstdArchive {\n  members: Map<string, Uint8Array>;\n  /** advisory ZIP comment; may be empty (2/56 samples have empty comments) */\n  zipComment: string;\n}\n\nexport type UnpackError =\n  | { kind: 'not-zip'; message: string }\n  | { kind: 'no-document-xml'; message: string };\n\n/**\n * Unpack an FCStd file. Only requirement: valid ZIP + root `Document.xml`.\n */\nexport function unpackFcstd(data: Uint8Array): Result<FcstdArchive, UnpackError> {\n  let entries: Record<string, Uint8Array>;\n  try {\n    entries = unzipSync(data);\n  } catch (e) {\n    return err({\n      kind: 'not-zip',\n      message: `cannot open as ZIP: ${e instanceof Error ? e.message : String(e)}`,\n    });\n  }\n  if (!('Document.xml' in entries)) {\n    return err({ kind: 'no-document-xml', message: 'root Document.xml not found in ZIP' });\n  }\n  // fflate does not expose the raw ZIP comment through unzipSync; read it\n  // directly from the EOCD record (22 bytes from end when comment is empty,\n  // else longer). Advisory only — never used for validation.\n  const comment = readZipComment(data) ?? '';\n  return ok({ members: new Map(Object.entries(entries)), zipComment: comment });\n}\n\nfunction readZipComment(data: Uint8Array): string | null {\n  // scan for EOCD signature 0x06054b50 from the end\n  for (let i = data.length - 22; i >= Math.max(0, data.length - 22 - 65535); i--) {\n    if (\n      data[i] === 0x50 && data[i + 1] === 0x4b && data[i + 2] === 0x05 && data[i + 3] === 0x06\n    ) {\n      const len = data[i + 20]! | (data[i + 21]! << 8);\n      const start = i + 22;\n      if (start + len > data.length) return null;\n      return new TextDecoder('latin1').decode(data.subarray(start, start + len));\n    }\n  }\n  return null;\n}\n\n/** UTF-8 text decode helper for XML members. */\nexport function memberText(archive: FcstdArchive, path: string): string | undefined {\n  const bytes = archive.members.get(path);\n  if (!bytes) return undefined;\n  return new TextDecoder('utf-8').decode(bytes);\n}\n"]}

package/dist/identity.d.ts

@@ -0,0 +1,229 @@
+/**
+ * identity.ts — 全仓唯一的 ID 品牌类型定义与信任点（f0，零依赖，可脱离 web 运行）
+ *
+ * See docs/api-contract.md §3 (naming contract: StmtId and PartName separation).
+ *
+ * ## 目标
+ *
+ * 为跨仓库（fai ↔ 3d_editor）传播的每一类 ID 建立唯一的 nominaal 品牌类型
+ * （`string & { readonly [__x]: true }`），并集中"string → 品牌"的全部转换
+ * （`as*` 信任点）。品牌类型不可互相赋值、不可由裸 string 赋值，错误在编译期暴露。
+ *
+ * ## 品牌清单（§0 术语表）
+ *
+ * | 品牌 | 语义 | 值域示例 |
+ * |---|---|---|
+ * | `FileId` | 文件身份（3d 场景树），无冒号 | UUID / `prim_1` |
+ * | `InnerId` | part 在文件内编号，无冒号 | `o1` / `part-0` |
+ * | `ScopedId` | `fileId:innerId`，恰好一个冒号（场景树 key） | `fileId:part-0` |
+ * | `StmtId` | 每条语句的 id（`ExecutionAnchor.id`），无赋值语句也有 | `s1` / `s<N>` |
+ * | `PartName` | 左值变量名（0/1/2 个，split 双值） | `part0` / `part<N>` |
+ * | `GroupName` | 装配/组语句的变量名（⊆ PartName） | `grp_<N>` |
+ * | `RefId` | 装配成员引用（scopedId 形态） | `fileId:part-0` |
+ * | `ReferenceId` | 拓扑选取 key（`topology\|<selType>\|<display>`） | `topology\|face\|o1.f1` |
+ * | `SelectorKey` | 用户可见 selector（剥前缀） | `o1.f1` / `f1` |
+ * | `OccurrenceId` | 拓扑行 occurrence id | `o1` / `o0.o1` |
+ * | `ShapeId` | 拓扑行 shape id | `o1.f0` |
+ * | `FaceId` | 拓扑行 face id | `o1.f1` |
+ * | `EdgeId` | 拓扑行 edge id | `o1.e1` |
+ * | `NodeId` | 场景树节点 key（= ScopedId 或 fileId 根）（3d 侧语义） | — |
+ *
+ * ## 禁止
+ * - `partId` 标识符（lint no-partid-identifier 唯一豁免 `lib/bambu-3mf/`）
+ * - 任何 `string` 直接赋值给品牌类型（编译期拦截）
+ * - 空串 / 回退兜底：`toScopedId`/`splitScopedId` 对非法输入抛错（CLAUDE.md 案例 2）
+ */
+declare const __fileId: unique symbol;
+declare const __innerId: unique symbol;
+declare const __scopedId: unique symbol;
+declare const __stmtId: unique symbol;
+declare const __partName: unique symbol;
+declare const __groupName: unique symbol;
+declare const __refId: unique symbol;
+declare const __referenceId: unique symbol;
+declare const __selectorKey: unique symbol;
+declare const __occurrenceId: unique symbol;
+declare const __shapeId: unique symbol;
+declare const __faceId: unique symbol;
+declare const __edgeId: unique symbol;
+declare const __nodeId: unique symbol;
+/** Branded ID: the file identity (3d scene tree node root), with no colon. */
+export type FileId = string & {
+    readonly [__fileId]: true;
+};
+/** Branded ID: a part's in-file number, with no colon. */
+export type InnerId = string & {
+    readonly [__innerId]: true;
+};
+/** Branded ID: `fileId:innerId` with exactly one colon (scene tree key). */
+export type ScopedId = string & {
+    readonly [__scopedId]: true;
+};
+/** Branded ID: a statement's id (ExecutionAnchor.id); every statement has one. */
+export type StmtId = string & {
+    readonly [__stmtId]: true;
+};
+/** Branded ID: a left-hand-side variable name; split outputs yield two values. */
+export type PartName = string & {
+    readonly [__partName]: true;
+};
+/** Branded ID: an assembly/group statement's variable name (`grp_N` ⊆ PartName). */
+export type GroupName = PartName & {
+    readonly [__groupName]: true;
+};
+/** Branded ID: an assembly member reference (scopedId shape). */
+export type RefId = string & {
+    readonly [__refId]: true;
+};
+/** Branded ID: a topology selection key (`topology|<selType>|<display>`). */
+export type ReferenceId = string & {
+    readonly [__referenceId]: true;
+};
+/** Branded ID: a user-visible selector (prefix-stripped). */
+export type SelectorKey = string & {
+    readonly [__selectorKey]: true;
+};
+/** Branded ID: a topology row occurrence id. */
+export type OccurrenceId = string & {
+    readonly [__occurrenceId]: true;
+};
+/** Branded ID: a topology row shape id. */
+export type ShapeId = string & {
+    readonly [__shapeId]: true;
+};
+/** Branded ID: a topology row face id. */
+export type FaceId = string & {
+    readonly [__faceId]: true;
+};
+/** Branded ID: a topology row edge id. */
+export type EdgeId = string & {
+    readonly [__edgeId]: true;
+};
+/** Branded ID: a scene tree node key (= ScopedId or a fileId root). */
+export type NodeId = string & {
+    readonly [__nodeId]: true;
+};
+/** Alias for StmtId (= ExecutionAnchor.id, distinct from PartName semantics). */
+export type StatementId = StmtId;
+/** Alias for FaceId (mesh FaceDescriptor carries no id; currently unused). */
+export type FaceSelector = FaceId;
+/**
+ * Trust point that converts a plain string to a branded FileId.
+ * @param raw - the raw string value.
+ * @returns the input typed as FileId.
+ */
+export declare function asFileId(raw: string): FileId;
+/**
+ * Trust point that converts a plain string to a branded InnerId.
+ * @param raw - the raw string value.
+ * @returns the input typed as InnerId.
+ */
+export declare function asInnerId(raw: string): InnerId;
+/**
+ * Trust point that converts a plain string to a branded ScopedId.
+ * @param raw - the raw string value.
+ * @returns the input typed as ScopedId.
+ */
+export declare function asScopedId(raw: string): ScopedId;
+/**
+ * Trust point that converts a plain string to a branded StmtId.
+ * @param raw - the raw string value.
+ * @returns the input typed as StmtId.
+ */
+export declare function asStmtId(raw: string): StmtId;
+/**
+ * Trust point that converts a plain string to a branded PartName.
+ * @param raw - the raw string value.
+ * @returns the input typed as PartName.
+ */
+export declare function asPartName(raw: string): PartName;
+/**
+ * Trust point that converts a plain string to a branded GroupName.
+ * @param raw - the raw string value.
+ * @returns the input typed as GroupName.
+ */
+export declare function asGroupName(raw: string): GroupName;
+/**
+ * Trust point that converts a plain string to a branded RefId.
+ * @param raw - the raw string value.
+ * @returns the input typed as RefId.
+ */
+export declare function asRefId(raw: string): RefId;
+/**
+ * Trust point that converts a plain string to a branded ReferenceId.
+ * @param raw - the raw string value.
+ * @returns the input typed as ReferenceId.
+ */
+export declare function asReferenceId(raw: string): ReferenceId;
+/**
+ * Trust point that converts a plain string to a branded SelectorKey.
+ * @param raw - the raw string value.
+ * @returns the input typed as SelectorKey.
+ */
+export declare function asSelectorKey(raw: string): SelectorKey;
+/**
+ * Trust point that converts a plain string to a branded OccurrenceId.
+ * @param raw - the raw string value.
+ * @returns the input typed as OccurrenceId.
+ */
+export declare function asOccurrenceId(raw: string): OccurrenceId;
+/**
+ * Trust point that converts a plain string to a branded ShapeId.
+ * @param raw - the raw string value.
+ * @returns the input typed as ShapeId.
+ */
+export declare function asShapeId(raw: string): ShapeId;
+/**
+ * Trust point that converts a plain string to a branded FaceId.
+ * @param raw - the raw string value.
+ * @returns the input typed as FaceId.
+ */
+export declare function asFaceId(raw: string): FaceId;
+/**
+ * Trust point that converts a plain string to a branded EdgeId.
+ * @param raw - the raw string value.
+ * @returns the input typed as EdgeId.
+ */
+export declare function asEdgeId(raw: string): EdgeId;
+/**
+ * Trust point that converts a plain string to a branded NodeId.
+ * @param raw - the raw string value.
+ * @returns the input typed as NodeId.
+ */
+export declare function asNodeId(raw: string): NodeId;
+/**
+ * Construct a scopedId = `${fileId}:${innerId}`. Asserts that neither fileId
+ * nor innerId contains a colon (preventing double prefixing) and throws on
+ * empty values.
+ * @param fileId - the file identity, without a colon.
+ * @param innerId - the part's in-file identity, without a colon.
+ * @returns the combined scopedId string.
+ */
+export declare function toScopedId(fileId: FileId, innerId: InnerId): ScopedId;
+/**
+ * The single split entry point: asserts the input has exactly one colon and
+ * returns the fileId and innerId components.
+ * @param scopedId - the scopedId to split.
+ * @returns an object with the fileId and innerId components.
+ */
+export declare function splitScopedId(scopedId: ScopedId): {
+    fileId: FileId;
+    innerId: InnerId;
+};
+/**
+ * Format check: whether the string is a scopedId (contains a colon). Note that
+ * a file root's nodeKey equals its fileId (no colon) and so returns false.
+ * @param s - the string to test.
+ * @returns true when the string is a scopedId, narrowing the type accordingly.
+ */
+export declare function isScopedId(s: string): s is ScopedId;
+/**
+ * Strip the `fileId:` prefix from a scopedId to obtain its innerId. Inputs
+ * without a colon (already an innerId) are returned unchanged — the caller is
+ * responsible for semantic correctness; this function only strips the prefix.
+ * @param raw - a scopedId or a bare innerId string.
+ * @returns the innerId portion of the input.
+ */
+export declare function toInnerId(raw: string): InnerId;
+export {};
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

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

package/dist/identity.js

@@ -0,0 +1,229 @@
+/**
+ * identity.ts — 全仓唯一的 ID 品牌类型定义与信任点（f0，零依赖，可脱离 web 运行）
+ *
+ * See docs/api-contract.md §3 (naming contract: StmtId and PartName separation).
+ *
+ * ## 目标
+ *
+ * 为跨仓库（fai ↔ 3d_editor）传播的每一类 ID 建立唯一的 nominaal 品牌类型
+ * （`string & { readonly [__x]: true }`），并集中"string → 品牌"的全部转换
+ * （`as*` 信任点）。品牌类型不可互相赋值、不可由裸 string 赋值，错误在编译期暴露。
+ *
+ * ## 品牌清单（§0 术语表）
+ *
+ * | 品牌 | 语义 | 值域示例 |
+ * |---|---|---|
+ * | `FileId` | 文件身份（3d 场景树），无冒号 | UUID / `prim_1` |
+ * | `InnerId` | part 在文件内编号，无冒号 | `o1` / `part-0` |
+ * | `ScopedId` | `fileId:innerId`，恰好一个冒号（场景树 key） | `fileId:part-0` |
+ * | `StmtId` | 每条语句的 id（`ExecutionAnchor.id`），无赋值语句也有 | `s1` / `s<N>` |
+ * | `PartName` | 左值变量名（0/1/2 个，split 双值） | `part0` / `part<N>` |
+ * | `GroupName` | 装配/组语句的变量名（⊆ PartName） | `grp_<N>` |
+ * | `RefId` | 装配成员引用（scopedId 形态） | `fileId:part-0` |
+ * | `ReferenceId` | 拓扑选取 key（`topology\|<selType>\|<display>`） | `topology\|face\|o1.f1` |
+ * | `SelectorKey` | 用户可见 selector（剥前缀） | `o1.f1` / `f1` |
+ * | `OccurrenceId` | 拓扑行 occurrence id | `o1` / `o0.o1` |
+ * | `ShapeId` | 拓扑行 shape id | `o1.f0` |
+ * | `FaceId` | 拓扑行 face id | `o1.f1` |
+ * | `EdgeId` | 拓扑行 edge id | `o1.e1` |
+ * | `NodeId` | 场景树节点 key（= ScopedId 或 fileId 根）（3d 侧语义） | — |
+ *
+ * ## 禁止
+ * - `partId` 标识符（lint no-partid-identifier 唯一豁免 `lib/bambu-3mf/`）
+ * - 任何 `string` 直接赋值给品牌类型（编译期拦截）
+ * - 空串 / 回退兜底：`toScopedId`/`splitScopedId` 对非法输入抛错（CLAUDE.md 案例 2）
+ */
+// ═════════════════════════════════════════════════════════════════════════
+// 唯一信任点（string → ID 的唯一大门）
+// ═════════════════════════════════════════════════════════════════════════
+/**
+ * Trust point that converts a plain string to a branded FileId.
+ * @param raw - the raw string value.
+ * @returns the input typed as FileId.
+ */
+export function asFileId(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded InnerId.
+ * @param raw - the raw string value.
+ * @returns the input typed as InnerId.
+ */
+export function asInnerId(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded ScopedId.
+ * @param raw - the raw string value.
+ * @returns the input typed as ScopedId.
+ */
+export function asScopedId(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded StmtId.
+ * @param raw - the raw string value.
+ * @returns the input typed as StmtId.
+ */
+export function asStmtId(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded PartName.
+ * @param raw - the raw string value.
+ * @returns the input typed as PartName.
+ */
+export function asPartName(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded GroupName.
+ * @param raw - the raw string value.
+ * @returns the input typed as GroupName.
+ */
+export function asGroupName(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded RefId.
+ * @param raw - the raw string value.
+ * @returns the input typed as RefId.
+ */
+export function asRefId(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded ReferenceId.
+ * @param raw - the raw string value.
+ * @returns the input typed as ReferenceId.
+ */
+export function asReferenceId(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded SelectorKey.
+ * @param raw - the raw string value.
+ * @returns the input typed as SelectorKey.
+ */
+export function asSelectorKey(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded OccurrenceId.
+ * @param raw - the raw string value.
+ * @returns the input typed as OccurrenceId.
+ */
+export function asOccurrenceId(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded ShapeId.
+ * @param raw - the raw string value.
+ * @returns the input typed as ShapeId.
+ */
+export function asShapeId(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded FaceId.
+ * @param raw - the raw string value.
+ * @returns the input typed as FaceId.
+ */
+export function asFaceId(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded EdgeId.
+ * @param raw - the raw string value.
+ * @returns the input typed as EdgeId.
+ */
+export function asEdgeId(raw) {
+    return raw;
+}
+/**
+ * Trust point that converts a plain string to a branded NodeId.
+ * @param raw - the raw string value.
+ * @returns the input typed as NodeId.
+ */
+export function asNodeId(raw) {
+    return raw;
+}
+// ═════════════════════════════════════════════════════════════════════════
+// ScopedId 构造 / 拆分（3d 场景树语义；fai 仅在此处实现，3d re-export）
+// ═════════════════════════════════════════════════════════════════════
+/**
+ * Construct a scopedId = `${fileId}:${innerId}`. Asserts that neither fileId
+ * nor innerId contains a colon (preventing double prefixing) and throws on
+ * empty values.
+ * @param fileId - the file identity, without a colon.
+ * @param innerId - the part's in-file identity, without a colon.
+ * @returns the combined scopedId string.
+ */
+export function toScopedId(fileId, innerId) {
+    if (!fileId)
+        throw new Error('[identity] toScopedId: fileId is empty');
+    if (!innerId)
+        throw new Error('[identity] toScopedId: innerId is empty');
+    if (fileId.includes(':')) {
+        throw new Error(`[identity] toScopedId: fileId "${fileId}" contains colon — did you pass a scopedId?`);
+    }
+    if (innerId.includes(':')) {
+        throw new Error(`[identity] toScopedId: innerId "${innerId}" contains colon — did you pass a scopedId?`);
+    }
+    return `${fileId}:${innerId}`;
+}
+/**
+ * The single split entry point: asserts the input has exactly one colon and
+ * returns the fileId and innerId components.
+ * @param scopedId - the scopedId to split.
+ * @returns an object with the fileId and innerId components.
+ */
+export function splitScopedId(scopedId) {
+    if (!scopedId)
+        throw new Error('[identity] splitScopedId: input is empty');
+    const colonIdx = scopedId.indexOf(':');
+    if (colonIdx === -1) {
+        throw new Error(`[identity] splitScopedId: "${scopedId}" — no colon found, not a scopedId`);
+    }
+    const fileId = scopedId.slice(0, colonIdx);
+    const innerId = scopedId.slice(colonIdx + 1);
+    if (!fileId)
+        throw new Error(`[identity] splitScopedId: "${scopedId}" — fileId is empty`);
+    if (!innerId)
+        throw new Error(`[identity] splitScopedId: "${scopedId}" — innerId is empty`);
+    if (innerId.includes(':')) {
+        throw new Error(`[identity] splitScopedId: "${scopedId}" — multiple colons, not a valid scopedId`);
+    }
+    return { fileId: fileId, innerId: innerId };
+}
+/**
+ * Format check: whether the string is a scopedId (contains a colon). Note that
+ * a file root's nodeKey equals its fileId (no colon) and so returns false.
+ * @param s - the string to test.
+ * @returns true when the string is a scopedId, narrowing the type accordingly.
+ */
+export function isScopedId(s) {
+    return s.includes(':');
+}
+/**
+ * Strip the `fileId:` prefix from a scopedId to obtain its innerId. Inputs
+ * without a colon (already an innerId) are returned unchanged — the caller is
+ * responsible for semantic correctness; this function only strips the prefix.
+ * @param raw - a scopedId or a bare innerId string.
+ * @returns the innerId portion of the input.
+ */
+export function toInnerId(raw) {
+    if (!raw)
+        throw new Error('[identity] toInnerId: input is empty');
+    const colonIdx = raw.indexOf(':');
+    if (colonIdx === -1)
+        return raw;
+    const stripped = raw.slice(colonIdx + 1);
+    if (!stripped)
+        throw new Error(`[identity] toInnerId: "${raw}" — innerId after colon is empty`);
+    if (stripped.includes(':')) {
+        throw new Error(`[identity] toInnerId: "${raw}" — multiple colons, cannot produce valid innerId`);
+    }
+    return stripped;
+}
+//# sourceMappingURL=identity.js.map