@profile-as-code/core 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Luciani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @profile-as-code/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The core engine of **profile-as-code** (M1): load a profile-data workspace,
+validate it against the contract, and run the drift / GEO / compile layers.
+
+The contract source is `schema/profile.schema.json` (D3) — Zod schemas are
+**generated** from it, never hand-written (see `scripts/gen-zod.ts`).
+
+## API
+
+```ts
+import { load, driftCheck, geoCheck, compile } from '@profile-as-code/core';
+
+const profile = load('/path/to/profile-data');        // parse content/*.yaml + validate (FAIL on schema, D12)
+const issues  = driftCheck(profile);                     // Issue[] — WARN only, never throws (D12)
+const geo     = geoCheck(profile);                       // GeoReport — 0..100 score, not a gate (§8)
+const slice   = compile(profile, 'linkedin', 'es');      // PlatformProfile — language-aware renderer slice
+```
+
+- **`load(workspace)`** — reads `content/*.yaml` (file name = root property:
+  `bios.yaml` → `bios[]`, `identity.yaml` → `identity`, …), merges, validates
+  against the generated Zod, normalizes (collections default to `[]`).
+  Throws `LoadError` (workspace problems) / `SchemaValidationError` (contract
+  violations with one precise `path` + `message` per error — the fail-on-schema
+  side of D12). Unknown files fail validation via `additionalProperties: false`.
+- **`driftCheck(profile)`** — factual contradictions across surfaces, all WARN
+  (users may have different intents per platform, but they must SEE them):
+  uncanonicalized platform URLs, `start > end`, duplicated bios/headlines,
+  same role/org with different dates, same title with different year/venue,
+  ORCID conflicts/mismatches vs `identity.links`, active entries without a
+  curated base, unknown active platform keys, skill level conflicts.
+  *Out of scope (v1):* free-text mining of bio prose, DOI resolvability
+  (network), the variants store (only the platform+lang base is validated).
+- **`geoCheck(profile)`** — weighted report (14 checks since v1.10, 0..100):
+  **fact consistency** (conflicts + per-platform bio/headline coverage),
+  **structured-data readiness** (`schema.org` Person JSON-LD with `sameAs`,
+  ready for the web renderer), **semantic associations** (the 3–5
+  `positioning.geo.semanticAssociations` anchors and how well each is
+  reinforced across statement/skills/keywords/projects), **citability**
+  (DOI/ORCID on publications, `evidence[]` on projects) plus the v1.10 citability
+  codes — canonical definition, FAQ coverage, freshness, sameAs coverage, name
+  collision. Missing data is neutral for the fact checks (never penalized);
+  readiness/citability checks (structured data, semantic anchors, the v1.10 codes)
+  can score 0 when the signal is absent — a reported gap, not a penalty (SPEC §8).
+- **`compile(profile, platform, lang)`** — facts pass through untouched
+  (identical on every platform = GEO-citable); text (bios, headlines, statement,
+  audiences, citationsGoal) is filtered by platform+lang and falls back to `en`
+  (always required by the schema), recording each fallback in `fallbacks`.
+
+## Contract fidelity (generator)
+
+`scripts/gen-zod.ts` regenerates `src/generated/schema.zod.ts` from
+`schema/profile.schema.json`. Because `json-schema-to-zod@2.8.1` does not resolve
+`$defs`, ignore `propertyNames`, and bloats `oneOf`, the generator:
+
+1. inlines `#/$defs/*` references (fails on unknown/circular defs),
+2. rewrites the lone `oneOf` (`check.value`) to `anyOf` (clean `z.union`),
+3. materializes `langMap.en` as a real property (keeps `required: ['en']`), and
+4. wraps every langMap with a `langMapKeys` superRefine enforcing the
+   `en/es/fr` key enum (`propertyNames`).
+
+Safety nets fail CI loudly if the output ever contains `z.any()` or loses the
+langMap guard.
+
+## Test
+
+```sh
+pnpm install
+pnpm test        # vitest (load, drift, geo, compile)
+pnpm build       # strict tsc → dist/
+pnpm gen:zod     # regenerate src/generated/schema.zod.ts (must produce no diff)
+```
+
+Fixtures live in `tests/fixtures/`: `minimal/` (drift-free, GEO-rich — the
+reference fixture) and `drifting/` (schema-valid but contradicts itself on
+every drift rule).
+
+Requires Node ≥ 22 (the `engines` field of this manifest). Full source and docs
+live in the [public repository](https://github.com/ChristianLuciani/profile-as-code) —
+`scripts/gen-zod.ts` and `tests/fixtures/` above are package-relative paths there
+(`packages/core/…`); the contract source is the repository's `schema/profile.schema.json`.

package/dist/byte-order.d.ts

@@ -0,0 +1,17 @@
+/**
+ * byte-order.ts — the ONE home of every text-order comparison in the engine
+ * (D19 byte-parity, issue #305).
+ *
+ * The comparator is UTF-16 code UNITS — JS native `a < b` string order:
+ * deterministic on every environment, ICU-free. It is NOT codepoint order on
+ * the astral edge, and SPEC §15.3 names that choice exactly. A `localeCompare`
+ * call-site would depend on the ICU build and can tie (`0`), leaking
+ * environment-specific order through a stable sort — the class #257 fixed for
+ * the featured slice and #305 closes workspace-wide.
+ *
+ * The discriminating probe (`apple` vs `APPLE`: ICU collation reads lowercase
+ * first, code units read uppercase first) lives at
+ * packages/core/tests/byte-order.test.ts.
+ */
+export declare function byteOrder(a: string, b: string): number;
+//# sourceMappingURL=byte-order.d.ts.map

package/dist/byte-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-order.d.ts","sourceRoot":"","sources":["../src/byte-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/byte-order.js

@@ -0,0 +1,19 @@
+/**
+ * byte-order.ts — the ONE home of every text-order comparison in the engine
+ * (D19 byte-parity, issue #305).
+ *
+ * The comparator is UTF-16 code UNITS — JS native `a < b` string order:
+ * deterministic on every environment, ICU-free. It is NOT codepoint order on
+ * the astral edge, and SPEC §15.3 names that choice exactly. A `localeCompare`
+ * call-site would depend on the ICU build and can tie (`0`), leaking
+ * environment-specific order through a stable sort — the class #257 fixed for
+ * the featured slice and #305 closes workspace-wide.
+ *
+ * The discriminating probe (`apple` vs `APPLE`: ICU collation reads lowercase
+ * first, code units read uppercase first) lives at
+ * packages/core/tests/byte-order.test.ts.
+ */
+export function byteOrder(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+//# sourceMappingURL=byte-order.js.map

package/dist/byte-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-order.js","sourceRoot":"","sources":["../src/byte-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CAAC,CAAS,EAAE,CAAS;IAC5C,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC"}

package/dist/cite.d.ts

@@ -0,0 +1,91 @@
+/**
+ * cite.ts — the deterministic citation matcher (SPEC §7.4, issue #291).
+ *
+ * The engine answers ONE question about an answer-engine record: did this saved
+ * answer cite this entity? It is a pure function over the SSOT and the answer
+ * bytes — no network, no model, no clock (D19) — because the alternative
+ * (substring matching) is why GEO reporting overreports, and the only fix is a
+ * matcher that says exactly which text it matched, why, and when it refuses to
+ * guess.
+ *
+ * The vocabulary is the workspace's DECLARED data, never world knowledge:
+ *   name     identity.name
+ *   alias    identity.orgName (the one declared alternate name the schema has)
+ *   handle   identity.handle (its final token, '@' stripped) + socialHandles
+ *            rows with status: claimed
+ *   hosts    the role: identity URL and the sameAs set (structured-data.ts —
+ *            one derivation, never a second)
+ *   partial  a contiguous multi-token prefix of the name (low confidence)
+ *
+ * Normalization and word-boundary matching live in `normalize.ts`. It is
+ * `cite-check`'s fold, not `geoCheck`'s: `geoCheck` keeps its own case-only
+ * comparison so this matcher cannot move a published GEO score (§8).
+ *
+ * Guards make a text hit NOT a citation (`cited: false`): a shorter term
+ * contained in a longer declared one (`longer-name`), a one-word name with no
+ * declared disambiguator in its sentence (`ambiguous-term` + `no-qualifier`), and
+ * a mention inside a contrast clause (`contrast-context`). `competing:<phrase>`
+ * never decides on its own — it only names the longer reading the text carries
+ * when the hit is already ambiguous, so ordinary prose cannot become a
+ * competitor through an adjacent capital. `confidence: low` is never citable
+ * downstream (declared in §7.4).
+ */
+import type { Profile } from "./types.js";
+/** The rung a span was matched by — one kind per ladder rung (SPEC §7.4). */
+export type CiteSpanKind = "citation-url" | "name" | "alias" | "handle" | "partial";
+/** The best surviving rung. `low` is never a citation in a downstream report. */
+export type CiteConfidence = "high" | "medium" | "low";
+/** One citation row of the runner's input contract. */
+export interface CiteCitation {
+    url: string;
+    title?: string;
+}
+/**
+ * One saved answer (the runner's contract, never produced here). The matcher
+ * reads `answer` + `citations`; the rest is carried through for a report.
+ */
+export interface CiteAnswer {
+    engine?: string | null;
+    askedAt?: string | null;
+    question?: string | null;
+    answer: string;
+    citations: CiteCitation[];
+}
+/** A matched span: a character range in `answer`, or a citation pointer. */
+export interface CiteSpan {
+    /** Original offset (inclusive). 0 for a `citation-url` span (not in the text). */
+    start: number;
+    /** Original offset (exclusive). 0 for a `citation-url` span. */
+    end: number;
+    kind: CiteSpanKind;
+    /** The citation URL — only on `citation-url` spans. */
+    url?: string;
+}
+/** Per-answer result. Never aggregated by the engine (SPEC §7.4). */
+export interface CiteMatch {
+    cited: boolean;
+    confidence: CiteConfidence;
+    spans: CiteSpan[];
+    reasons: string[];
+}
+/**
+ * The vocabulary the matcher resolved from the workspace. Exposed in `--json`
+ * so a report can say WHAT was matched without re-reading the SSOT.
+ */
+export interface CiteVocabulary {
+    name: string;
+    aliases: string[];
+    handles: string[];
+    partials: string[];
+    hosts: string[];
+}
+/** The public vocabulary of a workspace (the `entity` block of `--json`). */
+export declare function citeVocabulary(profile: Profile): CiteVocabulary;
+/**
+ * Match one saved answer against the workspace's declared entity (SPEC §7.4).
+ * Pure: the same profile + answer bytes always produce the same result.
+ */
+export declare function citeMatch(profile: Profile, answer: CiteAnswer): CiteMatch;
+/** Exported for tests: the declared host of a URL under the matcher's rule. */
+export declare function citationHost(url: string): string | undefined;
+//# sourceMappingURL=cite.d.ts.map

package/dist/cite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cite.d.ts","sourceRoot":"","sources":["../src/cite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEpF,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEvD,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED,4EAA4E;AAC5E,MAAM,WAAW,QAAQ;IACvB,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,YAAY,CAAC;IACnB,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,cAAc,CAAC;IAC3B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAsND,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,CAE/D;AAgFD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CA0JzE;AAaD,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE5D"}