@profile-as-code/core 0.1.1 → 0.1.3

package/dist/achievements.d.ts

@@ -0,0 +1,83 @@
+/**
+ * achievements.ts — the career impact log (D24, SPEC §23, issue #446).
+ *
+ * The contract models what a person DID (`experience[].highlights`) and what can
+ * be PROVEN (`projects[].evidence[]`), but not what CHANGED. This module owns the
+ * one thing the block cannot store: the **status**, DERIVED from the numbers at
+ * read time.
+ *
+ *   achievementStatus(a)   planned | measured | achieved | partial — or undefined
+ *                          for a milestone (a point event has no progress) and for
+ *                          a metric that declares neither `value` nor `target`
+ *                          (nothing to plan, nothing to measure).
+ *   achievementScope(list) the counters the CLI's `--json` `scope` reports, so
+ *                          "nothing measured" is distinguishable from "clean"
+ *                          (the `pasco audit` shape discipline, §7.1).
+ *   checkAchievementIntegrity(profile) the post-Zod contract checks the generated
+ *                          Zod cannot express (D12 fail class): duplicate ids,
+ *                          dangling `refs`/`artifactId`/`credentialId`, the
+ *                          `kind` ↔ `metric` invariant, and the §18.5 leak (a
+ *                          PUBLIC achievement pointing at a private credential or
+ *                          artifact). `load()` throws on any violation.
+ *
+ * Offline and deterministic (D19): no network, no clock, no AI. `direction` is
+ * OPTIONAL — absent means `increase`, a DECLARED default (never inferred from the
+ * baseline: a `72 → 4` row without a direction is `decrease` only if it says so).
+ */
+import { type RegistryIssue } from "./registry.js";
+import type { LoadedProfile, Profile } from "./types.js";
+/** A row of the impact log (schema v1.16, D24). */
+export type Achievement = NonNullable<LoadedProfile["achievements"]>[number];
+/** The numeric shape of a `metric` row. */
+export type AchievementMetric = NonNullable<Achievement["metric"]>;
+/** HOW the result is known — the honesty field, not a gate. */
+export type AchievementBasis = NonNullable<Achievement["basis"]>;
+/** Which way is better. */
+export type AchievementDirection = NonNullable<AchievementMetric["direction"]>;
+/** The DERIVED status. `planned` is a goal; `measured` a number with no goal. */
+export type AchievementStatus = "planned" | "measured" | "achieved" | "partial";
+/** Absent `direction` = `increase`. Declared here once; every reader calls it. */
+export declare const DEFAULT_ACHIEVEMENT_DIRECTION: AchievementDirection;
+/** The counters `pasco achievements --json` reports under `scope`. */
+export interface AchievementScope {
+    total: number;
+    planned: number;
+    measured: number;
+    achieved: number;
+    partial: number;
+}
+/**
+ * The DERIVED status of one row (never stored, §23):
+ *
+ *   target, no value            planned
+ *   value, no target            measured
+ *   both, direction met         achieved
+ *   both, direction not met     partial
+ *   kind: milestone             undefined (a point event has no progress)
+ *   metric with neither number  undefined (nothing to plan, nothing to measure)
+ *
+ * A `kind: milestone` row carrying a `metric` is a contract violation that
+ * `checkAchievementIntegrity` rejects at load; this function does not guess a
+ * status for it.
+ */
+export declare function achievementStatus(achievement: Achievement): AchievementStatus | undefined;
+/** The `scope` counters of a log: total plus one bucket per derived status. */
+export declare function achievementScope(achievements: readonly Achievement[]): AchievementScope;
+/** The blocks a `refs[]` entry may address — the schema's `refs` alternation and
+ *  this list must agree; `tests/achievements.test.ts` pins them against each
+ *  other (F6 of the pre-merge review: a hand-copy with no guard let a future
+ *  block added only to the schema make a valid ref fail `load` as dangling). */
+export declare const ACHIEVEMENT_REF_BLOCKS: readonly ["experience", "projects", "publications", "education", "press", "credentials", "artifacts"];
+/**
+ * Post-Zod contract checks for the impact log (load fails on any of them, D12):
+ *
+ * - duplicate `achievements[].id`;
+ * - a `refs[]`, `artifactId` or `credentialId` that does not resolve (same class
+ *   as the registry cross-refs: a dangling pointer is never silently ignored);
+ * - `kind: metric` without `metric` / `kind: milestone` with one — the `if/then`
+ *   the issue rejected is enforced here and in the CLI, not in JSON Schema;
+ * - a PUBLIC achievement pointing at a `private`/`unlisted` credential or artifact
+ *   (the §18.5 leak rule, same one `projects[].artifactRefs` answers to).
+ */
+export declare function checkAchievementIntegrity(profile: Profile): RegistryIssue[];
+//# sourceMappingURL=achievements.d.ts.map

package/dist/achievements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"achievements.d.ts","sourceRoot":"","sources":["../src/achievements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEzD,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7E,2CAA2C;AAC3C,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;AACnE,+DAA+D;AAC/D,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;AACjE,2BAA2B;AAC3B,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;AAC/E,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAEhF,kFAAkF;AAClF,eAAO,MAAM,6BAA6B,EAAE,oBAAiC,CAAC;AAE9E,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,WAAW,GAAG,iBAAiB,GAAG,SAAS,CAUzF;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,GAAG,gBAAgB,CAavF;AAED;;;gFAGgF;AAChF,eAAO,MAAM,sBAAsB,YACjC,YAAY,EACZ,UAAU,EACV,cAAc,EACd,WAAW,EACX,OAAO,EACP,aAAa,EACb,WAAW,CACH,CAAC;AA2BX;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,EAAE,CAsH3E"}

package/dist/achievements.js

@@ -0,0 +1,207 @@
+/**
+ * achievements.ts — the career impact log (D24, SPEC §23, issue #446).
+ *
+ * The contract models what a person DID (`experience[].highlights`) and what can
+ * be PROVEN (`projects[].evidence[]`), but not what CHANGED. This module owns the
+ * one thing the block cannot store: the **status**, DERIVED from the numbers at
+ * read time.
+ *
+ *   achievementStatus(a)   planned | measured | achieved | partial — or undefined
+ *                          for a milestone (a point event has no progress) and for
+ *                          a metric that declares neither `value` nor `target`
+ *                          (nothing to plan, nothing to measure).
+ *   achievementScope(list) the counters the CLI's `--json` `scope` reports, so
+ *                          "nothing measured" is distinguishable from "clean"
+ *                          (the `pasco audit` shape discipline, §7.1).
+ *   checkAchievementIntegrity(profile) the post-Zod contract checks the generated
+ *                          Zod cannot express (D12 fail class): duplicate ids,
+ *                          dangling `refs`/`artifactId`/`credentialId`, the
+ *                          `kind` ↔ `metric` invariant, and the §18.5 leak (a
+ *                          PUBLIC achievement pointing at a private credential or
+ *                          artifact). `load()` throws on any violation.
+ *
+ * Offline and deterministic (D19): no network, no clock, no AI. `direction` is
+ * OPTIONAL — absent means `increase`, a DECLARED default (never inferred from the
+ * baseline: a `72 → 4` row without a direction is `decrease` only if it says so).
+ */
+import { isPublicEntry } from "./registry.js";
+/** Absent `direction` = `increase`. Declared here once; every reader calls it. */
+export const DEFAULT_ACHIEVEMENT_DIRECTION = "increase";
+/**
+ * The DIRECTION verdict for a row that has both `value` and `target`.
+ * `increase`: value >= target · `decrease`: value <= target · `maintain`: equal.
+ */
+function directionMet(value, target, direction) {
+    switch (direction) {
+        case "increase":
+            return value >= target;
+        case "decrease":
+            return value <= target;
+        case "maintain":
+            return value === target;
+    }
+}
+/**
+ * The DERIVED status of one row (never stored, §23):
+ *
+ *   target, no value            planned
+ *   value, no target            measured
+ *   both, direction met         achieved
+ *   both, direction not met     partial
+ *   kind: milestone             undefined (a point event has no progress)
+ *   metric with neither number  undefined (nothing to plan, nothing to measure)
+ *
+ * A `kind: milestone` row carrying a `metric` is a contract violation that
+ * `checkAchievementIntegrity` rejects at load; this function does not guess a
+ * status for it.
+ */
+export function achievementStatus(achievement) {
+    if (achievement.kind !== "metric")
+        return undefined;
+    const metric = achievement.metric;
+    if (metric === undefined)
+        return undefined;
+    const { value, target } = metric;
+    if (target !== undefined && value === undefined)
+        return "planned";
+    if (value !== undefined && target === undefined)
+        return "measured";
+    if (value === undefined || target === undefined)
+        return undefined;
+    const direction = metric.direction ?? DEFAULT_ACHIEVEMENT_DIRECTION;
+    return directionMet(value, target, direction) ? "achieved" : "partial";
+}
+/** The `scope` counters of a log: total plus one bucket per derived status. */
+export function achievementScope(achievements) {
+    const scope = {
+        total: achievements.length,
+        planned: 0,
+        measured: 0,
+        achieved: 0,
+        partial: 0,
+    };
+    for (const achievement of achievements) {
+        const status = achievementStatus(achievement);
+        if (status !== undefined)
+            scope[status] += 1;
+    }
+    return scope;
+}
+/** The blocks a `refs[]` entry may address — the schema's `refs` alternation and
+ *  this list must agree; `tests/achievements.test.ts` pins them against each
+ *  other (F6 of the pre-merge review: a hand-copy with no guard let a future
+ *  block added only to the schema make a valid ref fail `load` as dangling). */
+export const ACHIEVEMENT_REF_BLOCKS = [
+    "experience",
+    "projects",
+    "publications",
+    "education",
+    "press",
+    "credentials",
+    "artifacts",
+];
+/** `block:id` ids the profile actually declares, per block. */
+function declaredIds(profile) {
+    const rows = {
+        experience: profile.experience,
+        projects: profile.projects,
+        publications: profile.publications,
+        education: profile.education,
+        press: profile.press,
+        credentials: profile.credentials,
+        artifacts: profile.artifacts,
+    };
+    const map = new Map();
+    for (const block of ACHIEVEMENT_REF_BLOCKS) {
+        const ids = new Set();
+        for (const row of rows[block] ?? [])
+            if (row.id !== undefined)
+                ids.add(row.id);
+        map.set(block, ids);
+    }
+    return map;
+}
+function issue(path, message) {
+    return { path, message };
+}
+/**
+ * Post-Zod contract checks for the impact log (load fails on any of them, D12):
+ *
+ * - duplicate `achievements[].id`;
+ * - a `refs[]`, `artifactId` or `credentialId` that does not resolve (same class
+ *   as the registry cross-refs: a dangling pointer is never silently ignored);
+ * - `kind: metric` without `metric` / `kind: milestone` with one — the `if/then`
+ *   the issue rejected is enforced here and in the CLI, not in JSON Schema;
+ * - a PUBLIC achievement pointing at a `private`/`unlisted` credential or artifact
+ *   (the §18.5 leak rule, same one `projects[].artifactRefs` answers to).
+ */
+export function checkAchievementIntegrity(profile) {
+    const issues = [];
+    const achievements = profile.achievements ?? [];
+    const ids = declaredIds(profile);
+    const credentials = profile.credentials ?? [];
+    const artifacts = profile.artifacts ?? [];
+    const seen = new Map();
+    for (const [index, achievement] of achievements.entries()) {
+        const first = seen.get(achievement.id);
+        if (first !== undefined) {
+            issues.push(issue(`achievements[${index}].id`, `duplicate achievement id "${achievement.id}" (first used at achievements[${first}]) — achievement ids are unique per block (load fails, D12 fail class)`));
+        }
+        else {
+            seen.set(achievement.id, index);
+        }
+        // kind ↔ metric (§23 — the two shapes are exclusive; `if/then` is not used).
+        if (achievement.kind === "metric" && achievement.metric === undefined) {
+            issues.push(issue(`achievements[${index}].metric`, `kind: metric requires a "metric" block (unit is required; value/target/baseline are the numbers) — without it there is no status to derive`));
+        }
+        if (achievement.kind === "milestone" && achievement.metric !== undefined) {
+            issues.push(issue(`achievements[${index}].metric`, `kind: milestone must NOT carry a "metric" block — a point event has no progress to derive; use kind: metric, or move the numbers into the statement`));
+        }
+        // refs[] — a dangling pointer is a load failure, not a warning.
+        for (const [refIndex, ref] of (achievement.refs ?? []).entries()) {
+            const separator = ref.indexOf(":");
+            const block = ref.slice(0, separator);
+            const id = ref.slice(separator + 1);
+            if (!ids.get(block)?.has(id)) {
+                issues.push(issue(`achievements[${index}].refs[${refIndex}]`, `references ${block}[].id "${id}" which does not exist (dangling cross-ref, load fails)`));
+            }
+        }
+        if (achievement.credentialId !== undefined) {
+            const credential = credentials.find((c) => c.id === achievement.credentialId);
+            if (credential === undefined) {
+                issues.push(issue(`achievements[${index}].credentialId`, `references credentials[].id "${achievement.credentialId}" which does not exist (dangling cross-ref, load fails)`));
+            }
+            else if (achievement.visibility === "public" && !isPublicEntry(credential)) {
+                issues.push(issue(`achievements[${index}].credentialId`, `a public achievement attests credential "${credential.id}" with visibility "${credential.visibility}" — public output renders only public entries (§18.5); make it public, or make the achievement non-public`));
+            }
+        }
+        if (achievement.artifactId !== undefined) {
+            const artifact = artifacts.find((a) => a.id === achievement.artifactId);
+            if (artifact === undefined) {
+                issues.push(issue(`achievements[${index}].artifactId`, `references artifacts[].id "${achievement.artifactId}" which does not exist (dangling cross-ref, load fails)`));
+            }
+            else if (achievement.visibility === "public" && !isPublicEntry(artifact)) {
+                issues.push(issue(`achievements[${index}].artifactId`, `a public achievement points at artifact "${artifact.id}" with visibility "${artifact.visibility}" — public output renders only public entries (§18.5); make it public, or make the achievement non-public`));
+            }
+        }
+        // A public achievement that references a private entry THROUGH refs[] is the
+        // same leak: the ref is what a renderer groups the row by.
+        if (achievement.visibility === "public") {
+            for (const [refIndex, ref] of (achievement.refs ?? []).entries()) {
+                const separator = ref.indexOf(":");
+                const block = ref.slice(0, separator);
+                const id = ref.slice(separator + 1);
+                const target = block === "credentials"
+                    ? credentials.find((c) => c.id === id)
+                    : block === "artifacts"
+                        ? artifacts.find((a) => a.id === id)
+                        : undefined;
+                if (target !== undefined && !isPublicEntry(target)) {
+                    issues.push(issue(`achievements[${index}].refs[${refIndex}]`, `a public achievement references ${block}[].id "${id}" with visibility "${target.visibility}" — public output renders only public entries (§18.5)`));
+                }
+            }
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=achievements.js.map

package/dist/achievements.js.map

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

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"}