Period engine — period keys, boundaries and due dates, timezone-correct

[os-warren]

Fixes#1

One module owns what a period is, so the dispatcher, the backfill and the seed cannot disagree about it. Pure functions, no I/O, no platform imports beyond types, and no new runtime dependency — Intl.DateTimeFormat with a timeZone supplies both the local calendar parts and, by comparing those parts against the instant, the zone's offset at that instant. That is everything the arithmetic needs.

Files

File
src/functions/period.ts	new — the engine
test/period.test.ts	new — 89 tests

src/functions/index.ts is untouched: dulyFunctions is the map a script flow node resolves by name, no flow exists yet, and #2 imports the functions directly. Adding a name nothing resolves would be dead metadata and a needless collision point for the other three branches in flight. objectstack.config.ts is untouched.

API

periodKeyFor(frequency,instant: Date,timezone: string): stringperiodBounds(frequency,periodKey: string,timezone: string): { start: Date; end: Date}// [start, end)dueDateFor({ frequency, periodKey, timezone, dueAnchor, dueOffsetDays }): string// YYYY-MM-DDvisibleFromFor(dueDate: string,leadDays: number): string// YYYY-MM-DDperiodsBetween(frequency,from: Date,to: Date,timezone: string): string[]// ascending

The key spelling table is implemented exactly as written on the issue, 2026-W04 padding included, and every key is checked against period_key's maxLength: 16.

The two decisions worth reviewing

1. The inversion verifies its answer instead of trusting a second pass. The textbook wall-clock-to-instant conversion (guess - offsetAt(guess - offsetAt(guess))) is not merely imprecise on a zone that shifts at midnight — it lands in the wrong period. For America/Santiago 2026-09-06, where local midnight does not exist, it converges on 2026-09-06T03:00Z, whose local reading is 23:00 on the 5th. So candidates are drawn from the offsets a day either side of the target and then verified against the zone: an exact match wins (earliest, when a fall-back makes the reading happen twice), otherwise the answer resolves forward to the first instant past the requested reading. Measured, not assumed — ablating this back to the naive two-pass turns two tests red (below).

2. periodsBetween returns only keys periodKeyFor could itself return. The first draft walked civil dates and emitted 2011-12-30 for Pacific/Apia — a local day the zone skipped when it crossed the date line. A backfill would have filed a task for a day nobody lived through, whose periodBounds window is empty. The walk now carries each boundary instant forward and skips a period with no instants in it; it costs one zone inversion per period, not two, because neighbours share a boundary.

Behaviour the tests pin

• Round-tripperiodKeyFor(f, periodBounds(f, k, tz).start, tz) === k for all seven frequencies × UTC / Europe/Berlin / Asia/Shanghai × ten awkward instants (year boundaries, both DST transitions, month ends, a leap day), plus the containment check that the probe falls inside the window it named.
• ISO week-years: 2026-01-01 → 2026-W01, 2027-01-01 → 2026-W53. 2020 and 2026 have 53 weeks; 2021-W53 is refused with the week count in the message.
• Fortnights start on odd ISO weeks and are named by the starting week. One consequence is worth stating out loud: in a 53-week week-year the final fortnight is one week long, because W01 of the next week-year must itself begin a fortnight and so cannot be the back half of this one. That is forced by the anchoring rule rather than chosen — the alternative reading (a 14-day cycle running continuously across the boundary) would mean W01 did not begin a fortnight in 2027, contradicting the contract. Periods stay contiguous and keys still round-trip either way; 2020 and 2026 both have a test.
• DST: Berlin 2026-03-29 is a 23-hour day that still starts at local midnight; Berlin 2026-10-25 is a 25-hour day that starts at the first of its two midnights; Santiago 2026-09-06 has no local midnight and resolves forward to 01:00, with its neighbour's end equal to its start.
• Clamping: period_start + 30 on February is the 28th, or the 29th in a leap year, never 2 March; period_end - 90 on a month is the 1st. A table drives ±9999 on both anchors across all seven frequencies and asserts the result never leaves the period.
• periodsBetween over the 2026→2027 boundary for each frequency: ascending, no duplicates, and contiguous by construction — each period's end is asserted equal to the next period's start.
• Malformed keys are refused, never repaired — 2026-W4, 2026-13, 2026-Q5, 2026-02-30, and an even fortnight key (whose message names the odd one you probably meant). duly_task is unique on (duty, owner, period_key), so two spellings of one period would be two tasks for one obligation and nothing downstream could tell they were meant to be the same.

Gates — all four green at 8946861

pnpm validate ✓ Validation passed (232ms)
pnpm typecheck tsc --noEmit, no output
pnpm test Test Files 2 passed (2) · Tests 97 passed (97)
pnpm build ✓ Build complete · dist/objectstack.json (51.7 KB)

97 = the 89 added here plus the 8 existing invariant tests, which still pass untouched.

Reverse verification

Each mutation was confirmed on disk (injected marker present, removed anchor absent, git diff --stat non-empty) before the run, and a shell trap restored the tree after each leg; the tree was verified clean and marker-free afterwards. No build step is involved — vitest transforms src/ directly, so there is no dist/ for a stale artifact to hide in.

Ablation	Result
Inversion replaced with the naive unverified two-pass	2 failed — the Santiago midnight-shift test and the skipped-day test
Clamp removed from dueDateFor	5 failed — the February leap pair and all four clamping tests
Fortnights always 14 days (53-week year ignored)	3 failed — both 53-week tests and the periodsBetween fortnightly walk

Raised, not changed

• Fix the self-contradictory due_offset_days description (reading A adjudicated) #23 — duly_duty.due_offset_days's description contradicts itself: "Days from the anchor" and "5" … = due on the 5th cannot both hold, since a monthly period starts on the 1st. This PR implements days from the anchor, with 0 meaning the anchor day, because defaultValue: 0 has to mean something on both anchors and period_end + 0 = the last day is the worked example in duty.object.ts and docs/product/data-model.md alike. Both readings satisfy every clamped example in Period engine — period keys, boundaries and due dates, timezone-correct #1's acceptance criteria, so the gates cannot separate them — a person should confirm before Dispatcher job — idempotent task generation, backfill-capable #2 and Demo seed data — the product working on first boot #7 bake one in. If the other reading wins, it is a one-day shift in dueDateFor plus two tests.
• duly_duty.timezone accepts any string — a typo'd IANA zone validates clean and fails at dispatch #24 — duly_duty.timezone accepts any string, so a typo'd IANA zone validates clean and first throws inside the dispatcher. The engine refuses an unknown zone deliberately (a duty silently resolving in the wrong zone is a wrong due date nobody can see), which is why the check wants to exist at author time too.

Neither is touched here: both live on src/objects/, outside this card's file surface.

Generated by Claude Code

---

Generated by Claude Code

[os-warren]

Fixes#1

One module owns what a period is, so the dispatcher, the backfill and the seed cannot disagree about it. Pure functions, no I/O, no platform imports beyond types, and no new runtime dependency — Intl.DateTimeFormat with a timeZone supplies both the local calendar parts and, by comparing those parts against the instant, the zone's offset at that instant. That is everything the arithmetic needs.

Files

File
src/functions/period.ts	new — the engine
test/period.test.ts	new — 89 tests

src/functions/index.ts is untouched: dulyFunctions is the map a script flow node resolves by name, no flow exists yet, and #2 imports the functions directly. Adding a name nothing resolves would be dead metadata and a needless collision point for the other three branches in flight. objectstack.config.ts is untouched.

API

periodKeyFor(frequency,instant: Date,timezone: string): stringperiodBounds(frequency,periodKey: string,timezone: string): { start: Date; end: Date}// [start, end)dueDateFor({ frequency, periodKey, timezone, dueAnchor, dueOffsetDays }): string// YYYY-MM-DDvisibleFromFor(dueDate: string,leadDays: number): string// YYYY-MM-DDperiodsBetween(frequency,from: Date,to: Date,timezone: string): string[]// ascending

The key spelling table is implemented exactly as written on the issue, 2026-W04 padding included, and every key is checked against period_key's maxLength: 16.

The two decisions worth reviewing

1. The inversion verifies its answer instead of trusting a second pass. The textbook wall-clock-to-instant conversion (guess - offsetAt(guess - offsetAt(guess))) is not merely imprecise on a zone that shifts at midnight — it lands in the wrong period. For America/Santiago 2026-09-06, where local midnight does not exist, it converges on 2026-09-06T03:00Z, whose local reading is 23:00 on the 5th. So candidates are drawn from the offsets a day either side of the target and then verified against the zone: an exact match wins (earliest, when a fall-back makes the reading happen twice), otherwise the answer resolves forward to the first instant past the requested reading. Measured, not assumed — ablating this back to the naive two-pass turns two tests red (below).

2. periodsBetween returns only keys periodKeyFor could itself return. The first draft walked civil dates and emitted 2011-12-30 for Pacific/Apia — a local day the zone skipped when it crossed the date line. A backfill would have filed a task for a day nobody lived through, whose periodBounds window is empty. The walk now carries each boundary instant forward and skips a period with no instants in it; it costs one zone inversion per period, not two, because neighbours share a boundary.

Behaviour the tests pin

• Round-tripperiodKeyFor(f, periodBounds(f, k, tz).start, tz) === k for all seven frequencies × UTC / Europe/Berlin / Asia/Shanghai × ten awkward instants (year boundaries, both DST transitions, month ends, a leap day), plus the containment check that the probe falls inside the window it named.
• ISO week-years: 2026-01-01 → 2026-W01, 2027-01-01 → 2026-W53. 2020 and 2026 have 53 weeks; 2021-W53 is refused with the week count in the message.
• Fortnights start on odd ISO weeks and are named by the starting week. One consequence is worth stating out loud: in a 53-week week-year the final fortnight is one week long, because W01 of the next week-year must itself begin a fortnight and so cannot be the back half of this one. That is forced by the anchoring rule rather than chosen — the alternative reading (a 14-day cycle running continuously across the boundary) would mean W01 did not begin a fortnight in 2027, contradicting the contract. Periods stay contiguous and keys still round-trip either way; 2020 and 2026 both have a test.
• DST: Berlin 2026-03-29 is a 23-hour day that still starts at local midnight; Berlin 2026-10-25 is a 25-hour day that starts at the first of its two midnights; Santiago 2026-09-06 has no local midnight and resolves forward to 01:00, with its neighbour's end equal to its start.
• Clamping: period_start + 30 on February is the 28th, or the 29th in a leap year, never 2 March; period_end - 90 on a month is the 1st. A table drives ±9999 on both anchors across all seven frequencies and asserts the result never leaves the period.
• periodsBetween over the 2026→2027 boundary for each frequency: ascending, no duplicates, and contiguous by construction — each period's end is asserted equal to the next period's start.
• Malformed keys are refused, never repaired — 2026-W4, 2026-13, 2026-Q5, 2026-02-30, and an even fortnight key (whose message names the odd one you probably meant). duly_task is unique on (duty, owner, period_key), so two spellings of one period would be two tasks for one obligation and nothing downstream could tell they were meant to be the same.

Gates — all four green at 8946861

pnpm validate ✓ Validation passed (232ms)
pnpm typecheck tsc --noEmit, no output
pnpm test Test Files 2 passed (2) · Tests 97 passed (97)
pnpm build ✓ Build complete · dist/objectstack.json (51.7 KB)

97 = the 89 added here plus the 8 existing invariant tests, which still pass untouched.

Reverse verification

Each mutation was confirmed on disk (injected marker present, removed anchor absent, git diff --stat non-empty) before the run, and a shell trap restored the tree after each leg; the tree was verified clean and marker-free afterwards. No build step is involved — vitest transforms src/ directly, so there is no dist/ for a stale artifact to hide in.

Ablation	Result
Inversion replaced with the naive unverified two-pass	2 failed — the Santiago midnight-shift test and the skipped-day test
Clamp removed from dueDateFor	5 failed — the February leap pair and all four clamping tests
Fortnights always 14 days (53-week year ignored)	3 failed — both 53-week tests and the periodsBetween fortnightly walk

Raised, not changed

• Fix the self-contradictory due_offset_days description (reading A adjudicated) #23 — duly_duty.due_offset_days's description contradicts itself: "Days from the anchor" and "5" … = due on the 5th cannot both hold, since a monthly period starts on the 1st. This PR implements days from the anchor, with 0 meaning the anchor day, because defaultValue: 0 has to mean something on both anchors and period_end + 0 = the last day is the worked example in duty.object.ts and docs/product/data-model.md alike. Both readings satisfy every clamped example in Period engine — period keys, boundaries and due dates, timezone-correct #1's acceptance criteria, so the gates cannot separate them — a person should confirm before Dispatcher job — idempotent task generation, backfill-capable #2 and Demo seed data — the product working on first boot #7 bake one in. If the other reading wins, it is a one-day shift in dueDateFor plus two tests.
• duly_duty.timezone accepts any string — a typo'd IANA zone validates clean and fails at dispatch #24 — duly_duty.timezone accepts any string, so a typo'd IANA zone validates clean and first throws inside the dispatcher. The engine refuses an unknown zone deliberately (a duty silently resolving in the wrong zone is a wrong due date nobody can see), which is why the check wants to exist at author time too.

Neither is touched here: both live on src/objects/, outside this card's file surface.

Generated by Claude Code

---

Generated by Claude Code

[os-warren]

Fixes#1

One module owns what a period is, so the dispatcher, the backfill and the seed cannot disagree about it. Pure functions, no I/O, no platform imports beyond types, and no new runtime dependency — Intl.DateTimeFormat with a timeZone supplies both the local calendar parts and, by comparing those parts against the instant, the zone's offset at that instant. That is everything the arithmetic needs.

Files

File
src/functions/period.ts	new — the engine
test/period.test.ts	new — 89 tests

src/functions/index.ts is untouched: dulyFunctions is the map a script flow node resolves by name, no flow exists yet, and #2 imports the functions directly. Adding a name nothing resolves would be dead metadata and a needless collision point for the other three branches in flight. objectstack.config.ts is untouched.

API

periodKeyFor(frequency,instant: Date,timezone: string): stringperiodBounds(frequency,periodKey: string,timezone: string): { start: Date; end: Date}// [start, end)dueDateFor({ frequency, periodKey, timezone, dueAnchor, dueOffsetDays }): string// YYYY-MM-DDvisibleFromFor(dueDate: string,leadDays: number): string// YYYY-MM-DDperiodsBetween(frequency,from: Date,to: Date,timezone: string): string[]// ascending

The key spelling table is implemented exactly as written on the issue, 2026-W04 padding included, and every key is checked against period_key's maxLength: 16.

The two decisions worth reviewing

1. The inversion verifies its answer instead of trusting a second pass. The textbook wall-clock-to-instant conversion (guess - offsetAt(guess - offsetAt(guess))) is not merely imprecise on a zone that shifts at midnight — it lands in the wrong period. For America/Santiago 2026-09-06, where local midnight does not exist, it converges on 2026-09-06T03:00Z, whose local reading is 23:00 on the 5th. So candidates are drawn from the offsets a day either side of the target and then verified against the zone: an exact match wins (earliest, when a fall-back makes the reading happen twice), otherwise the answer resolves forward to the first instant past the requested reading. Measured, not assumed — ablating this back to the naive two-pass turns two tests red (below).

2. periodsBetween returns only keys periodKeyFor could itself return. The first draft walked civil dates and emitted 2011-12-30 for Pacific/Apia — a local day the zone skipped when it crossed the date line. A backfill would have filed a task for a day nobody lived through, whose periodBounds window is empty. The walk now carries each boundary instant forward and skips a period with no instants in it; it costs one zone inversion per period, not two, because neighbours share a boundary.

Behaviour the tests pin

• Round-tripperiodKeyFor(f, periodBounds(f, k, tz).start, tz) === k for all seven frequencies × UTC / Europe/Berlin / Asia/Shanghai × ten awkward instants (year boundaries, both DST transitions, month ends, a leap day), plus the containment check that the probe falls inside the window it named.
• ISO week-years: 2026-01-01 → 2026-W01, 2027-01-01 → 2026-W53. 2020 and 2026 have 53 weeks; 2021-W53 is refused with the week count in the message.
• Fortnights start on odd ISO weeks and are named by the starting week. One consequence is worth stating out loud: in a 53-week week-year the final fortnight is one week long, because W01 of the next week-year must itself begin a fortnight and so cannot be the back half of this one. That is forced by the anchoring rule rather than chosen — the alternative reading (a 14-day cycle running continuously across the boundary) would mean W01 did not begin a fortnight in 2027, contradicting the contract. Periods stay contiguous and keys still round-trip either way; 2020 and 2026 both have a test.
• DST: Berlin 2026-03-29 is a 23-hour day that still starts at local midnight; Berlin 2026-10-25 is a 25-hour day that starts at the first of its two midnights; Santiago 2026-09-06 has no local midnight and resolves forward to 01:00, with its neighbour's end equal to its start.
• Clamping: period_start + 30 on February is the 28th, or the 29th in a leap year, never 2 March; period_end - 90 on a month is the 1st. A table drives ±9999 on both anchors across all seven frequencies and asserts the result never leaves the period.
• periodsBetween over the 2026→2027 boundary for each frequency: ascending, no duplicates, and contiguous by construction — each period's end is asserted equal to the next period's start.
• Malformed keys are refused, never repaired — 2026-W4, 2026-13, 2026-Q5, 2026-02-30, and an even fortnight key (whose message names the odd one you probably meant). duly_task is unique on (duty, owner, period_key), so two spellings of one period would be two tasks for one obligation and nothing downstream could tell they were meant to be the same.

Gates — all four green at 8946861

pnpm validate ✓ Validation passed (232ms)
pnpm typecheck tsc --noEmit, no output
pnpm test Test Files 2 passed (2) · Tests 97 passed (97)
pnpm build ✓ Build complete · dist/objectstack.json (51.7 KB)

97 = the 89 added here plus the 8 existing invariant tests, which still pass untouched.

Reverse verification

Each mutation was confirmed on disk (injected marker present, removed anchor absent, git diff --stat non-empty) before the run, and a shell trap restored the tree after each leg; the tree was verified clean and marker-free afterwards. No build step is involved — vitest transforms src/ directly, so there is no dist/ for a stale artifact to hide in.

Ablation	Result
Inversion replaced with the naive unverified two-pass	2 failed — the Santiago midnight-shift test and the skipped-day test
Clamp removed from dueDateFor	5 failed — the February leap pair and all four clamping tests
Fortnights always 14 days (53-week year ignored)	3 failed — both 53-week tests and the periodsBetween fortnightly walk

Raised, not changed

• Fix the self-contradictory due_offset_days description (reading A adjudicated) #23 — duly_duty.due_offset_days's description contradicts itself: "Days from the anchor" and "5" … = due on the 5th cannot both hold, since a monthly period starts on the 1st. This PR implements days from the anchor, with 0 meaning the anchor day, because defaultValue: 0 has to mean something on both anchors and period_end + 0 = the last day is the worked example in duty.object.ts and docs/product/data-model.md alike. Both readings satisfy every clamped example in Period engine — period keys, boundaries and due dates, timezone-correct #1's acceptance criteria, so the gates cannot separate them — a person should confirm before Dispatcher job — idempotent task generation, backfill-capable #2 and Demo seed data — the product working on first boot #7 bake one in. If the other reading wins, it is a one-day shift in dueDateFor plus two tests.
• duly_duty.timezone accepts any string — a typo'd IANA zone validates clean and fails at dispatch #24 — duly_duty.timezone accepts any string, so a typo'd IANA zone validates clean and first throws inside the dispatcher. The engine refuses an unknown zone deliberately (a duty silently resolving in the wrong zone is a wrong due date nobody can see), which is why the check wants to exist at author time too.

Neither is touched here: both live on src/objects/, outside this card's file surface.

Generated by Claude Code

---

Generated by Claude Code

[os-warren]

Fixes#1

One module owns what a period is, so the dispatcher, the backfill and the seed cannot disagree about it. Pure functions, no I/O, no platform imports beyond types, and no new runtime dependency — Intl.DateTimeFormat with a timeZone supplies both the local calendar parts and, by comparing those parts against the instant, the zone's offset at that instant. That is everything the arithmetic needs.

Files

File
src/functions/period.ts	new — the engine
test/period.test.ts	new — 89 tests

src/functions/index.ts is untouched: dulyFunctions is the map a script flow node resolves by name, no flow exists yet, and #2 imports the functions directly. Adding a name nothing resolves would be dead metadata and a needless collision point for the other three branches in flight. objectstack.config.ts is untouched.

API

periodKeyFor(frequency,instant: Date,timezone: string): stringperiodBounds(frequency,periodKey: string,timezone: string): { start: Date; end: Date}// [start, end)dueDateFor({ frequency, periodKey, timezone, dueAnchor, dueOffsetDays }): string// YYYY-MM-DDvisibleFromFor(dueDate: string,leadDays: number): string// YYYY-MM-DDperiodsBetween(frequency,from: Date,to: Date,timezone: string): string[]// ascending

The key spelling table is implemented exactly as written on the issue, 2026-W04 padding included, and every key is checked against period_key's maxLength: 16.

The two decisions worth reviewing

1. The inversion verifies its answer instead of trusting a second pass. The textbook wall-clock-to-instant conversion (guess - offsetAt(guess - offsetAt(guess))) is not merely imprecise on a zone that shifts at midnight — it lands in the wrong period. For America/Santiago 2026-09-06, where local midnight does not exist, it converges on 2026-09-06T03:00Z, whose local reading is 23:00 on the 5th. So candidates are drawn from the offsets a day either side of the target and then verified against the zone: an exact match wins (earliest, when a fall-back makes the reading happen twice), otherwise the answer resolves forward to the first instant past the requested reading. Measured, not assumed — ablating this back to the naive two-pass turns two tests red (below).

2. periodsBetween returns only keys periodKeyFor could itself return. The first draft walked civil dates and emitted 2011-12-30 for Pacific/Apia — a local day the zone skipped when it crossed the date line. A backfill would have filed a task for a day nobody lived through, whose periodBounds window is empty. The walk now carries each boundary instant forward and skips a period with no instants in it; it costs one zone inversion per period, not two, because neighbours share a boundary.

Behaviour the tests pin

• Round-tripperiodKeyFor(f, periodBounds(f, k, tz).start, tz) === k for all seven frequencies × UTC / Europe/Berlin / Asia/Shanghai × ten awkward instants (year boundaries, both DST transitions, month ends, a leap day), plus the containment check that the probe falls inside the window it named.
• ISO week-years: 2026-01-01 → 2026-W01, 2027-01-01 → 2026-W53. 2020 and 2026 have 53 weeks; 2021-W53 is refused with the week count in the message.
• Fortnights start on odd ISO weeks and are named by the starting week. One consequence is worth stating out loud: in a 53-week week-year the final fortnight is one week long, because W01 of the next week-year must itself begin a fortnight and so cannot be the back half of this one. That is forced by the anchoring rule rather than chosen — the alternative reading (a 14-day cycle running continuously across the boundary) would mean W01 did not begin a fortnight in 2027, contradicting the contract. Periods stay contiguous and keys still round-trip either way; 2020 and 2026 both have a test.
• DST: Berlin 2026-03-29 is a 23-hour day that still starts at local midnight; Berlin 2026-10-25 is a 25-hour day that starts at the first of its two midnights; Santiago 2026-09-06 has no local midnight and resolves forward to 01:00, with its neighbour's end equal to its start.
• Clamping: period_start + 30 on February is the 28th, or the 29th in a leap year, never 2 March; period_end - 90 on a month is the 1st. A table drives ±9999 on both anchors across all seven frequencies and asserts the result never leaves the period.
• periodsBetween over the 2026→2027 boundary for each frequency: ascending, no duplicates, and contiguous by construction — each period's end is asserted equal to the next period's start.
• Malformed keys are refused, never repaired — 2026-W4, 2026-13, 2026-Q5, 2026-02-30, and an even fortnight key (whose message names the odd one you probably meant). duly_task is unique on (duty, owner, period_key), so two spellings of one period would be two tasks for one obligation and nothing downstream could tell they were meant to be the same.

Gates — all four green at 8946861

pnpm validate ✓ Validation passed (232ms)
pnpm typecheck tsc --noEmit, no output
pnpm test Test Files 2 passed (2) · Tests 97 passed (97)
pnpm build ✓ Build complete · dist/objectstack.json (51.7 KB)

97 = the 89 added here plus the 8 existing invariant tests, which still pass untouched.

Reverse verification

Each mutation was confirmed on disk (injected marker present, removed anchor absent, git diff --stat non-empty) before the run, and a shell trap restored the tree after each leg; the tree was verified clean and marker-free afterwards. No build step is involved — vitest transforms src/ directly, so there is no dist/ for a stale artifact to hide in.

Ablation	Result
Inversion replaced with the naive unverified two-pass	2 failed — the Santiago midnight-shift test and the skipped-day test
Clamp removed from dueDateFor	5 failed — the February leap pair and all four clamping tests
Fortnights always 14 days (53-week year ignored)	3 failed — both 53-week tests and the periodsBetween fortnightly walk

Raised, not changed

• Fix the self-contradictory due_offset_days description (reading A adjudicated) #23 — duly_duty.due_offset_days's description contradicts itself: "Days from the anchor" and "5" … = due on the 5th cannot both hold, since a monthly period starts on the 1st. This PR implements days from the anchor, with 0 meaning the anchor day, because defaultValue: 0 has to mean something on both anchors and period_end + 0 = the last day is the worked example in duty.object.ts and docs/product/data-model.md alike. Both readings satisfy every clamped example in Period engine — period keys, boundaries and due dates, timezone-correct #1's acceptance criteria, so the gates cannot separate them — a person should confirm before Dispatcher job — idempotent task generation, backfill-capable #2 and Demo seed data — the product working on first boot #7 bake one in. If the other reading wins, it is a one-day shift in dueDateFor plus two tests.
• duly_duty.timezone accepts any string — a typo'd IANA zone validates clean and fails at dispatch #24 — duly_duty.timezone accepts any string, so a typo'd IANA zone validates clean and first throws inside the dispatcher. The engine refuses an unknown zone deliberately (a duty silently resolving in the wrong zone is a wrong due date nobody can see), which is why the check wants to exist at author time too.

Neither is touched here: both live on src/objects/, outside this card's file surface.

Generated by Claude Code

---

Generated by Claude Code

[os-warren]

Fixes#1

One module owns what a period is, so the dispatcher, the backfill and the seed cannot disagree about it. Pure functions, no I/O, no platform imports beyond types, and no new runtime dependency — Intl.DateTimeFormat with a timeZone supplies both the local calendar parts and, by comparing those parts against the instant, the zone's offset at that instant. That is everything the arithmetic needs.

Files

File
src/functions/period.ts	new — the engine
test/period.test.ts	new — 89 tests

src/functions/index.ts is untouched: dulyFunctions is the map a script flow node resolves by name, no flow exists yet, and #2 imports the functions directly. Adding a name nothing resolves would be dead metadata and a needless collision point for the other three branches in flight. objectstack.config.ts is untouched.

API

periodKeyFor(frequency,instant: Date,timezone: string): stringperiodBounds(frequency,periodKey: string,timezone: string): { start: Date; end: Date}// [start, end)dueDateFor({ frequency, periodKey, timezone, dueAnchor, dueOffsetDays }): string// YYYY-MM-DDvisibleFromFor(dueDate: string,leadDays: number): string// YYYY-MM-DDperiodsBetween(frequency,from: Date,to: Date,timezone: string): string[]// ascending

The key spelling table is implemented exactly as written on the issue, 2026-W04 padding included, and every key is checked against period_key's maxLength: 16.

The two decisions worth reviewing

1. The inversion verifies its answer instead of trusting a second pass. The textbook wall-clock-to-instant conversion (guess - offsetAt(guess - offsetAt(guess))) is not merely imprecise on a zone that shifts at midnight — it lands in the wrong period. For America/Santiago 2026-09-06, where local midnight does not exist, it converges on 2026-09-06T03:00Z, whose local reading is 23:00 on the 5th. So candidates are drawn from the offsets a day either side of the target and then verified against the zone: an exact match wins (earliest, when a fall-back makes the reading happen twice), otherwise the answer resolves forward to the first instant past the requested reading. Measured, not assumed — ablating this back to the naive two-pass turns two tests red (below).

2. periodsBetween returns only keys periodKeyFor could itself return. The first draft walked civil dates and emitted 2011-12-30 for Pacific/Apia — a local day the zone skipped when it crossed the date line. A backfill would have filed a task for a day nobody lived through, whose periodBounds window is empty. The walk now carries each boundary instant forward and skips a period with no instants in it; it costs one zone inversion per period, not two, because neighbours share a boundary.

Behaviour the tests pin

• Round-tripperiodKeyFor(f, periodBounds(f, k, tz).start, tz) === k for all seven frequencies × UTC / Europe/Berlin / Asia/Shanghai × ten awkward instants (year boundaries, both DST transitions, month ends, a leap day), plus the containment check that the probe falls inside the window it named.
• ISO week-years: 2026-01-01 → 2026-W01, 2027-01-01 → 2026-W53. 2020 and 2026 have 53 weeks; 2021-W53 is refused with the week count in the message.
• Fortnights start on odd ISO weeks and are named by the starting week. One consequence is worth stating out loud: in a 53-week week-year the final fortnight is one week long, because W01 of the next week-year must itself begin a fortnight and so cannot be the back half of this one. That is forced by the anchoring rule rather than chosen — the alternative reading (a 14-day cycle running continuously across the boundary) would mean W01 did not begin a fortnight in 2027, contradicting the contract. Periods stay contiguous and keys still round-trip either way; 2020 and 2026 both have a test.
• DST: Berlin 2026-03-29 is a 23-hour day that still starts at local midnight; Berlin 2026-10-25 is a 25-hour day that starts at the first of its two midnights; Santiago 2026-09-06 has no local midnight and resolves forward to 01:00, with its neighbour's end equal to its start.
• Clamping: period_start + 30 on February is the 28th, or the 29th in a leap year, never 2 March; period_end - 90 on a month is the 1st. A table drives ±9999 on both anchors across all seven frequencies and asserts the result never leaves the period.
• periodsBetween over the 2026→2027 boundary for each frequency: ascending, no duplicates, and contiguous by construction — each period's end is asserted equal to the next period's start.
• Malformed keys are refused, never repaired — 2026-W4, 2026-13, 2026-Q5, 2026-02-30, and an even fortnight key (whose message names the odd one you probably meant). duly_task is unique on (duty, owner, period_key), so two spellings of one period would be two tasks for one obligation and nothing downstream could tell they were meant to be the same.

Gates — all four green at 8946861

pnpm validate ✓ Validation passed (232ms)
pnpm typecheck tsc --noEmit, no output
pnpm test Test Files 2 passed (2) · Tests 97 passed (97)
pnpm build ✓ Build complete · dist/objectstack.json (51.7 KB)

97 = the 89 added here plus the 8 existing invariant tests, which still pass untouched.

Reverse verification

Each mutation was confirmed on disk (injected marker present, removed anchor absent, git diff --stat non-empty) before the run, and a shell trap restored the tree after each leg; the tree was verified clean and marker-free afterwards. No build step is involved — vitest transforms src/ directly, so there is no dist/ for a stale artifact to hide in.

Ablation	Result
Inversion replaced with the naive unverified two-pass	2 failed — the Santiago midnight-shift test and the skipped-day test
Clamp removed from dueDateFor	5 failed — the February leap pair and all four clamping tests
Fortnights always 14 days (53-week year ignored)	3 failed — both 53-week tests and the periodsBetween fortnightly walk

Raised, not changed

• Fix the self-contradictory due_offset_days description (reading A adjudicated) #23 — duly_duty.due_offset_days's description contradicts itself: "Days from the anchor" and "5" … = due on the 5th cannot both hold, since a monthly period starts on the 1st. This PR implements days from the anchor, with 0 meaning the anchor day, because defaultValue: 0 has to mean something on both anchors and period_end + 0 = the last day is the worked example in duty.object.ts and docs/product/data-model.md alike. Both readings satisfy every clamped example in Period engine — period keys, boundaries and due dates, timezone-correct #1's acceptance criteria, so the gates cannot separate them — a person should confirm before Dispatcher job — idempotent task generation, backfill-capable #2 and Demo seed data — the product working on first boot #7 bake one in. If the other reading wins, it is a one-day shift in dueDateFor plus two tests.
• duly_duty.timezone accepts any string — a typo'd IANA zone validates clean and fails at dispatch #24 — duly_duty.timezone accepts any string, so a typo'd IANA zone validates clean and first throws inside the dispatcher. The engine refuses an unknown zone deliberately (a duty silently resolving in the wrong zone is a wrong due date nobody can see), which is why the check wants to exist at author time too.

Neither is touched here: both live on src/objects/, outside this card's file surface.

Generated by Claude Code

---

Generated by Claude Code

[os-warren]

Fixes#1

One module owns what a period is, so the dispatcher, the backfill and the seed cannot disagree about it. Pure functions, no I/O, no platform imports beyond types, and no new runtime dependency — Intl.DateTimeFormat with a timeZone supplies both the local calendar parts and, by comparing those parts against the instant, the zone's offset at that instant. That is everything the arithmetic needs.

Files

File
src/functions/period.ts	new — the engine
test/period.test.ts	new — 89 tests

src/functions/index.ts is untouched: dulyFunctions is the map a script flow node resolves by name, no flow exists yet, and #2 imports the functions directly. Adding a name nothing resolves would be dead metadata and a needless collision point for the other three branches in flight. objectstack.config.ts is untouched.

API

periodKeyFor(frequency,instant: Date,timezone: string): stringperiodBounds(frequency,periodKey: string,timezone: string): { start: Date; end: Date}// [start, end)dueDateFor({ frequency, periodKey, timezone, dueAnchor, dueOffsetDays }): string// YYYY-MM-DDvisibleFromFor(dueDate: string,leadDays: number): string// YYYY-MM-DDperiodsBetween(frequency,from: Date,to: Date,timezone: string): string[]// ascending

The key spelling table is implemented exactly as written on the issue, 2026-W04 padding included, and every key is checked against period_key's maxLength: 16.

The two decisions worth reviewing

1. The inversion verifies its answer instead of trusting a second pass. The textbook wall-clock-to-instant conversion (guess - offsetAt(guess - offsetAt(guess))) is not merely imprecise on a zone that shifts at midnight — it lands in the wrong period. For America/Santiago 2026-09-06, where local midnight does not exist, it converges on 2026-09-06T03:00Z, whose local reading is 23:00 on the 5th. So candidates are drawn from the offsets a day either side of the target and then verified against the zone: an exact match wins (earliest, when a fall-back makes the reading happen twice), otherwise the answer resolves forward to the first instant past the requested reading. Measured, not assumed — ablating this back to the naive two-pass turns two tests red (below).

2. periodsBetween returns only keys periodKeyFor could itself return. The first draft walked civil dates and emitted 2011-12-30 for Pacific/Apia — a local day the zone skipped when it crossed the date line. A backfill would have filed a task for a day nobody lived through, whose periodBounds window is empty. The walk now carries each boundary instant forward and skips a period with no instants in it; it costs one zone inversion per period, not two, because neighbours share a boundary.

Behaviour the tests pin

• Round-tripperiodKeyFor(f, periodBounds(f, k, tz).start, tz) === k for all seven frequencies × UTC / Europe/Berlin / Asia/Shanghai × ten awkward instants (year boundaries, both DST transitions, month ends, a leap day), plus the containment check that the probe falls inside the window it named.
• ISO week-years: 2026-01-01 → 2026-W01, 2027-01-01 → 2026-W53. 2020 and 2026 have 53 weeks; 2021-W53 is refused with the week count in the message.
• Fortnights start on odd ISO weeks and are named by the starting week. One consequence is worth stating out loud: in a 53-week week-year the final fortnight is one week long, because W01 of the next week-year must itself begin a fortnight and so cannot be the back half of this one. That is forced by the anchoring rule rather than chosen — the alternative reading (a 14-day cycle running continuously across the boundary) would mean W01 did not begin a fortnight in 2027, contradicting the contract. Periods stay contiguous and keys still round-trip either way; 2020 and 2026 both have a test.
• DST: Berlin 2026-03-29 is a 23-hour day that still starts at local midnight; Berlin 2026-10-25 is a 25-hour day that starts at the first of its two midnights; Santiago 2026-09-06 has no local midnight and resolves forward to 01:00, with its neighbour's end equal to its start.
• Clamping: period_start + 30 on February is the 28th, or the 29th in a leap year, never 2 March; period_end - 90 on a month is the 1st. A table drives ±9999 on both anchors across all seven frequencies and asserts the result never leaves the period.
• periodsBetween over the 2026→2027 boundary for each frequency: ascending, no duplicates, and contiguous by construction — each period's end is asserted equal to the next period's start.
• Malformed keys are refused, never repaired — 2026-W4, 2026-13, 2026-Q5, 2026-02-30, and an even fortnight key (whose message names the odd one you probably meant). duly_task is unique on (duty, owner, period_key), so two spellings of one period would be two tasks for one obligation and nothing downstream could tell they were meant to be the same.

Gates — all four green at 8946861

pnpm validate ✓ Validation passed (232ms)
pnpm typecheck tsc --noEmit, no output
pnpm test Test Files 2 passed (2) · Tests 97 passed (97)
pnpm build ✓ Build complete · dist/objectstack.json (51.7 KB)

97 = the 89 added here plus the 8 existing invariant tests, which still pass untouched.

Reverse verification

Each mutation was confirmed on disk (injected marker present, removed anchor absent, git diff --stat non-empty) before the run, and a shell trap restored the tree after each leg; the tree was verified clean and marker-free afterwards. No build step is involved — vitest transforms src/ directly, so there is no dist/ for a stale artifact to hide in.

Ablation	Result
Inversion replaced with the naive unverified two-pass	2 failed — the Santiago midnight-shift test and the skipped-day test
Clamp removed from dueDateFor	5 failed — the February leap pair and all four clamping tests
Fortnights always 14 days (53-week year ignored)	3 failed — both 53-week tests and the periodsBetween fortnightly walk

Raised, not changed

• Fix the self-contradictory due_offset_days description (reading A adjudicated) #23 — duly_duty.due_offset_days's description contradicts itself: "Days from the anchor" and "5" … = due on the 5th cannot both hold, since a monthly period starts on the 1st. This PR implements days from the anchor, with 0 meaning the anchor day, because defaultValue: 0 has to mean something on both anchors and period_end + 0 = the last day is the worked example in duty.object.ts and docs/product/data-model.md alike. Both readings satisfy every clamped example in Period engine — period keys, boundaries and due dates, timezone-correct #1's acceptance criteria, so the gates cannot separate them — a person should confirm before Dispatcher job — idempotent task generation, backfill-capable #2 and Demo seed data — the product working on first boot #7 bake one in. If the other reading wins, it is a one-day shift in dueDateFor plus two tests.
• duly_duty.timezone accepts any string — a typo'd IANA zone validates clean and fails at dispatch #24 — duly_duty.timezone accepts any string, so a typo'd IANA zone validates clean and first throws inside the dispatcher. The engine refuses an unknown zone deliberately (a duty silently resolving in the wrong zone is a wrong due date nobody can see), which is why the check wants to exist at author time too.

Neither is touched here: both live on src/objects/, outside this card's file surface.

Generated by Claude Code

---

Generated by Claude Code

[os-warren]

Fixes#1

One module owns what a period is, so the dispatcher, the backfill and the seed cannot disagree about it. Pure functions, no I/O, no platform imports beyond types, and no new runtime dependency — Intl.DateTimeFormat with a timeZone supplies both the local calendar parts and, by comparing those parts against the instant, the zone's offset at that instant. That is everything the arithmetic needs.

Files

File
src/functions/period.ts	new — the engine
test/period.test.ts	new — 89 tests

src/functions/index.ts is untouched: dulyFunctions is the map a script flow node resolves by name, no flow exists yet, and #2 imports the functions directly. Adding a name nothing resolves would be dead metadata and a needless collision point for the other three branches in flight. objectstack.config.ts is untouched.

API

periodKeyFor(frequency,instant: Date,timezone: string): stringperiodBounds(frequency,periodKey: string,timezone: string): { start: Date; end: Date}// [start, end)dueDateFor({ frequency, periodKey, timezone, dueAnchor, dueOffsetDays }): string// YYYY-MM-DDvisibleFromFor(dueDate: string,leadDays: number): string// YYYY-MM-DDperiodsBetween(frequency,from: Date,to: Date,timezone: string): string[]// ascending

The key spelling table is implemented exactly as written on the issue, 2026-W04 padding included, and every key is checked against period_key's maxLength: 16.

The two decisions worth reviewing

1. The inversion verifies its answer instead of trusting a second pass. The textbook wall-clock-to-instant conversion (guess - offsetAt(guess - offsetAt(guess))) is not merely imprecise on a zone that shifts at midnight — it lands in the wrong period. For America/Santiago 2026-09-06, where local midnight does not exist, it converges on 2026-09-06T03:00Z, whose local reading is 23:00 on the 5th. So candidates are drawn from the offsets a day either side of the target and then verified against the zone: an exact match wins (earliest, when a fall-back makes the reading happen twice), otherwise the answer resolves forward to the first instant past the requested reading. Measured, not assumed — ablating this back to the naive two-pass turns two tests red (below).

2. periodsBetween returns only keys periodKeyFor could itself return. The first draft walked civil dates and emitted 2011-12-30 for Pacific/Apia — a local day the zone skipped when it crossed the date line. A backfill would have filed a task for a day nobody lived through, whose periodBounds window is empty. The walk now carries each boundary instant forward and skips a period with no instants in it; it costs one zone inversion per period, not two, because neighbours share a boundary.

Behaviour the tests pin

• Round-tripperiodKeyFor(f, periodBounds(f, k, tz).start, tz) === k for all seven frequencies × UTC / Europe/Berlin / Asia/Shanghai × ten awkward instants (year boundaries, both DST transitions, month ends, a leap day), plus the containment check that the probe falls inside the window it named.
• ISO week-years: 2026-01-01 → 2026-W01, 2027-01-01 → 2026-W53. 2020 and 2026 have 53 weeks; 2021-W53 is refused with the week count in the message.
• Fortnights start on odd ISO weeks and are named by the starting week. One consequence is worth stating out loud: in a 53-week week-year the final fortnight is one week long, because W01 of the next week-year must itself begin a fortnight and so cannot be the back half of this one. That is forced by the anchoring rule rather than chosen — the alternative reading (a 14-day cycle running continuously across the boundary) would mean W01 did not begin a fortnight in 2027, contradicting the contract. Periods stay contiguous and keys still round-trip either way; 2020 and 2026 both have a test.
• DST: Berlin 2026-03-29 is a 23-hour day that still starts at local midnight; Berlin 2026-10-25 is a 25-hour day that starts at the first of its two midnights; Santiago 2026-09-06 has no local midnight and resolves forward to 01:00, with its neighbour's end equal to its start.
• Clamping: period_start + 30 on February is the 28th, or the 29th in a leap year, never 2 March; period_end - 90 on a month is the 1st. A table drives ±9999 on both anchors across all seven frequencies and asserts the result never leaves the period.
• periodsBetween over the 2026→2027 boundary for each frequency: ascending, no duplicates, and contiguous by construction — each period's end is asserted equal to the next period's start.
• Malformed keys are refused, never repaired — 2026-W4, 2026-13, 2026-Q5, 2026-02-30, and an even fortnight key (whose message names the odd one you probably meant). duly_task is unique on (duty, owner, period_key), so two spellings of one period would be two tasks for one obligation and nothing downstream could tell they were meant to be the same.

Gates — all four green at 8946861

pnpm validate ✓ Validation passed (232ms)
pnpm typecheck tsc --noEmit, no output
pnpm test Test Files 2 passed (2) · Tests 97 passed (97)
pnpm build ✓ Build complete · dist/objectstack.json (51.7 KB)

97 = the 89 added here plus the 8 existing invariant tests, which still pass untouched.

Reverse verification

Each mutation was confirmed on disk (injected marker present, removed anchor absent, git diff --stat non-empty) before the run, and a shell trap restored the tree after each leg; the tree was verified clean and marker-free afterwards. No build step is involved — vitest transforms src/ directly, so there is no dist/ for a stale artifact to hide in.

Ablation	Result
Inversion replaced with the naive unverified two-pass	2 failed — the Santiago midnight-shift test and the skipped-day test
Clamp removed from dueDateFor	5 failed — the February leap pair and all four clamping tests
Fortnights always 14 days (53-week year ignored)	3 failed — both 53-week tests and the periodsBetween fortnightly walk

Raised, not changed

• Fix the self-contradictory due_offset_days description (reading A adjudicated) #23 — duly_duty.due_offset_days's description contradicts itself: "Days from the anchor" and "5" … = due on the 5th cannot both hold, since a monthly period starts on the 1st. This PR implements days from the anchor, with 0 meaning the anchor day, because defaultValue: 0 has to mean something on both anchors and period_end + 0 = the last day is the worked example in duty.object.ts and docs/product/data-model.md alike. Both readings satisfy every clamped example in Period engine — period keys, boundaries and due dates, timezone-correct #1's acceptance criteria, so the gates cannot separate them — a person should confirm before Dispatcher job — idempotent task generation, backfill-capable #2 and Demo seed data — the product working on first boot #7 bake one in. If the other reading wins, it is a one-day shift in dueDateFor plus two tests.
• duly_duty.timezone accepts any string — a typo'd IANA zone validates clean and fails at dispatch #24 — duly_duty.timezone accepts any string, so a typo'd IANA zone validates clean and first throws inside the dispatcher. The engine refuses an unknown zone deliberately (a duty silently resolving in the wrong zone is a wrong due date nobody can see), which is why the check wants to exist at author time too.

Neither is touched here: both live on src/objects/, outside this card's file surface.

Generated by Claude Code

---

Generated by Claude Code

[os-warren]

Fixes#1

One module owns what a period is, so the dispatcher, the backfill and the seed cannot disagree about it. Pure functions, no I/O, no platform imports beyond types, and no new runtime dependency — Intl.DateTimeFormat with a timeZone supplies both the local calendar parts and, by comparing those parts against the instant, the zone's offset at that instant. That is everything the arithmetic needs.

Files

File
src/functions/period.ts	new — the engine
test/period.test.ts	new — 89 tests

src/functions/index.ts is untouched: dulyFunctions is the map a script flow node resolves by name, no flow exists yet, and #2 imports the functions directly. Adding a name nothing resolves would be dead metadata and a needless collision point for the other three branches in flight. objectstack.config.ts is untouched.

API

periodKeyFor(frequency,instant: Date,timezone: string): stringperiodBounds(frequency,periodKey: string,timezone: string): { start: Date; end: Date}// [start, end)dueDateFor({ frequency, periodKey, timezone, dueAnchor, dueOffsetDays }): string// YYYY-MM-DDvisibleFromFor(dueDate: string,leadDays: number): string// YYYY-MM-DDperiodsBetween(frequency,from: Date,to: Date,timezone: string): string[]// ascending

The key spelling table is implemented exactly as written on the issue, 2026-W04 padding included, and every key is checked against period_key's maxLength: 16.

The two decisions worth reviewing

1. The inversion verifies its answer instead of trusting a second pass. The textbook wall-clock-to-instant conversion (guess - offsetAt(guess - offsetAt(guess))) is not merely imprecise on a zone that shifts at midnight — it lands in the wrong period. For America/Santiago 2026-09-06, where local midnight does not exist, it converges on 2026-09-06T03:00Z, whose local reading is 23:00 on the 5th. So candidates are drawn from the offsets a day either side of the target and then verified against the zone: an exact match wins (earliest, when a fall-back makes the reading happen twice), otherwise the answer resolves forward to the first instant past the requested reading. Measured, not assumed — ablating this back to the naive two-pass turns two tests red (below).

2. periodsBetween returns only keys periodKeyFor could itself return. The first draft walked civil dates and emitted 2011-12-30 for Pacific/Apia — a local day the zone skipped when it crossed the date line. A backfill would have filed a task for a day nobody lived through, whose periodBounds window is empty. The walk now carries each boundary instant forward and skips a period with no instants in it; it costs one zone inversion per period, not two, because neighbours share a boundary.

Behaviour the tests pin

• Round-tripperiodKeyFor(f, periodBounds(f, k, tz).start, tz) === k for all seven frequencies × UTC / Europe/Berlin / Asia/Shanghai × ten awkward instants (year boundaries, both DST transitions, month ends, a leap day), plus the containment check that the probe falls inside the window it named.
• ISO week-years: 2026-01-01 → 2026-W01, 2027-01-01 → 2026-W53. 2020 and 2026 have 53 weeks; 2021-W53 is refused with the week count in the message.
• Fortnights start on odd ISO weeks and are named by the starting week. One consequence is worth stating out loud: in a 53-week week-year the final fortnight is one week long, because W01 of the next week-year must itself begin a fortnight and so cannot be the back half of this one. That is forced by the anchoring rule rather than chosen — the alternative reading (a 14-day cycle running continuously across the boundary) would mean W01 did not begin a fortnight in 2027, contradicting the contract. Periods stay contiguous and keys still round-trip either way; 2020 and 2026 both have a test.
• DST: Berlin 2026-03-29 is a 23-hour day that still starts at local midnight; Berlin 2026-10-25 is a 25-hour day that starts at the first of its two midnights; Santiago 2026-09-06 has no local midnight and resolves forward to 01:00, with its neighbour's end equal to its start.
• Clamping: period_start + 30 on February is the 28th, or the 29th in a leap year, never 2 March; period_end - 90 on a month is the 1st. A table drives ±9999 on both anchors across all seven frequencies and asserts the result never leaves the period.
• periodsBetween over the 2026→2027 boundary for each frequency: ascending, no duplicates, and contiguous by construction — each period's end is asserted equal to the next period's start.
• Malformed keys are refused, never repaired — 2026-W4, 2026-13, 2026-Q5, 2026-02-30, and an even fortnight key (whose message names the odd one you probably meant). duly_task is unique on (duty, owner, period_key), so two spellings of one period would be two tasks for one obligation and nothing downstream could tell they were meant to be the same.

Gates — all four green at 8946861

pnpm validate ✓ Validation passed (232ms)
pnpm typecheck tsc --noEmit, no output
pnpm test Test Files 2 passed (2) · Tests 97 passed (97)
pnpm build ✓ Build complete · dist/objectstack.json (51.7 KB)

97 = the 89 added here plus the 8 existing invariant tests, which still pass untouched.

Reverse verification

Each mutation was confirmed on disk (injected marker present, removed anchor absent, git diff --stat non-empty) before the run, and a shell trap restored the tree after each leg; the tree was verified clean and marker-free afterwards. No build step is involved — vitest transforms src/ directly, so there is no dist/ for a stale artifact to hide in.

Ablation	Result
Inversion replaced with the naive unverified two-pass	2 failed — the Santiago midnight-shift test and the skipped-day test
Clamp removed from dueDateFor	5 failed — the February leap pair and all four clamping tests
Fortnights always 14 days (53-week year ignored)	3 failed — both 53-week tests and the periodsBetween fortnightly walk

Raised, not changed

• Fix the self-contradictory due_offset_days description (reading A adjudicated) #23 — duly_duty.due_offset_days's description contradicts itself: "Days from the anchor" and "5" … = due on the 5th cannot both hold, since a monthly period starts on the 1st. This PR implements days from the anchor, with 0 meaning the anchor day, because defaultValue: 0 has to mean something on both anchors and period_end + 0 = the last day is the worked example in duty.object.ts and docs/product/data-model.md alike. Both readings satisfy every clamped example in Period engine — period keys, boundaries and due dates, timezone-correct #1's acceptance criteria, so the gates cannot separate them — a person should confirm before Dispatcher job — idempotent task generation, backfill-capable #2 and Demo seed data — the product working on first boot #7 bake one in. If the other reading wins, it is a one-day shift in dueDateFor plus two tests.
• duly_duty.timezone accepts any string — a typo'd IANA zone validates clean and fails at dispatch #24 — duly_duty.timezone accepts any string, so a typo'd IANA zone validates clean and first throws inside the dispatcher. The engine refuses an unknown zone deliberately (a duty silently resolving in the wrong zone is a wrong due date nobody can see), which is why the check wants to exist at author time too.

Neither is touched here: both live on src/objects/, outside this card's file surface.

Generated by Claude Code

---

Generated by Claude Code